Environment configuration files in Ruby on Rails - Deep Dive

Overview - Environment configuration files

What is it?

Environment configuration files in Rails are special files that store settings and secrets for different stages of your app, like development, testing, and production. They help your app know how to behave depending on where it runs. These files keep sensitive data like passwords safe and separate from your main code. This way, you can change settings without touching the app's code.

Why it matters

Without environment configuration files, you would have to hardcode sensitive information and settings directly into your app, risking security and making it hard to change settings for different situations. This could lead to mistakes like exposing passwords or breaking your app when moving from development to production. Using these files makes your app safer, easier to manage, and more flexible.

Where it fits

Before learning environment configuration files, you should understand basic Rails app structure and how apps run in different modes (development, test, production). After this, you can learn about secrets management, environment variables, and deployment practices that rely on these configurations.

Mental Model

Core Idea

Environment configuration files act like a control panel that tells your Rails app how to behave safely and correctly in different places.

Think of it like...

It's like having different sets of house keys and instructions for your home depending on whether you're living there, visiting, or having guests. Each set controls what you can do and keeps things secure.

┌───────────────────────────────┐
│ Rails App                    │
│ ┌───────────────┐            │
│ │ Environment   │            │
│ │ Configuration │────────────┼─> Settings & Secrets
│ │ Files         │            │
│ └───────────────┘            │
│                               │
│ Modes: Development, Test, Prod│
└───────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

What Are Environment Files

Concept: Introduce the basic idea of environment configuration files and their role in Rails.

Rails uses files like config/environments/development.rb, test.rb, and production.rb to hold settings specific to each mode. These files tell Rails how to behave, such as showing detailed errors in development but hiding them in production.

Result

You understand that these files separate settings so your app acts differently in development, testing, and production.

Knowing that Rails separates settings by environment helps you avoid mixing development details with live app behavior.

2

Foundation

Using environment variables safely

Concept: Explain how environment variables store sensitive data outside code.

Instead of putting passwords or API keys directly in code, Rails apps use environment variables accessed via ENV['KEY_NAME']. These variables are set outside the app, keeping secrets safe and flexible.

Result

You can keep secrets like database passwords out of your code and change them without editing files.

Understanding environment variables prevents accidental exposure of sensitive data and makes your app more secure.

3

Intermediate

Configuring environments with files

🤔Before reading on: do you think all environment files share the same settings or have unique ones? Commit to your answer.

Concept: Show how each environment file customizes Rails behavior for its purpose.

Each file in config/environments/ overrides default settings. For example, development.rb enables code reloading and detailed errors, while production.rb enables caching and disables debugging. This customization ensures the app runs optimally in each environment.

Result

You can tailor your app's behavior by editing the right environment file.

Knowing that environment files override defaults helps you control app behavior precisely for each stage.

4

Intermediate

Using credentials and secrets.yml

🤔Before reading on: do you think Rails stores secrets in plain text or encrypted form? Commit to your answer.

Concept: Introduce Rails encrypted credentials and legacy secrets.yml for storing sensitive info.

Rails 5.2+ uses encrypted credentials stored in config/credentials.yml.enc, unlocked by a master key. This keeps secrets safe in version control. Older apps use config/secrets.yml, which is less secure. You access these secrets in code via Rails.application.credentials or Rails.application.secrets.

Result

You can securely store and access secrets without exposing them in code or repos.

Understanding encrypted credentials protects your app from leaking sensitive data even if code is shared.

5

Advanced

Managing multiple environments in deployment

🤔Before reading on: do you think deployment uses the same environment files as development? Commit to your answer.

Concept: Explain how environment configuration files affect deployment and running on servers.

When deploying, you set RAILS_ENV to production so Rails loads production.rb and production credentials. You also set environment variables on the server. This ensures the app runs with correct settings and secrets in production, separate from development or test.

Result

Your app behaves correctly and securely on live servers, avoiding development-only features.

Knowing how deployment uses environment configs prevents bugs and security issues caused by wrong settings.

6

Expert

Custom environment files and runtime changes

🤔Before reading on: can you change environment settings while the app runs, or only before start? Commit to your answer.

Concept: Explore advanced use of custom environment files and dynamic config changes.

You can create custom environment files like staging.rb for special cases. Also, some settings can be changed at runtime using Rails.application.config or gems like dotenv for loading env vars dynamically. However, many settings require app restart to take effect.

Result

You can adapt your app to complex deployment needs and tweak behavior without full redeploys.

Understanding runtime config flexibility helps build robust apps that adapt to changing environments.

Under the Hood

Rails loads environment configuration files during boot based on the RAILS_ENV variable. It first loads config/application.rb for defaults, then overrides with config/environments/#{RAILS_ENV}.rb. Environment variables are accessed via the ENV hash, which reads from the OS environment. Encrypted credentials are decrypted at boot using the master key, making secrets available securely in memory.

Why designed this way?

This design separates concerns: default app settings live in application.rb, while environment-specific tweaks live in separate files. Using environment variables and encrypted credentials keeps secrets out of code and version control, improving security. This layered approach balances flexibility, security, and ease of use.

┌───────────────────────────────┐
│ Rails Boot Process            │
│ ┌─────────────────────────┐ │
│ │ config/application.rb    │ │
│ └─────────────┬───────────┘ │
│               │ Overrides     │
│ ┌─────────────▼───────────┐ │
│ │ config/environments/    │ │
│ │ #{RAILS_ENV}.rb         │ │
│ └─────────────┬───────────┘ │
│               │ Loads env vars│
│ ┌─────────────▼───────────┐ │
│ │ ENV (OS environment)    │ │
│ └─────────────┬───────────┘ │
│               │ Decrypts     │
│ ┌─────────────▼───────────┐ │
│ │ config/credentials.yml.enc│
│ └─────────────────────────┘ │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think environment variables are automatically loaded by Rails without setup? Commit to yes or no.

Common Belief: Rails automatically loads all environment variables from a file without extra setup.

Reality: Rails reads environment variables from the OS environment. To load from files like .env, you need extra gems like dotenv.

Why it matters: Assuming automatic loading can cause missing variables in production, leading to app crashes or security leaks.

Quick: Do you think secrets.yml is as secure as encrypted credentials? Commit to yes or no.

Common Belief: Using secrets.yml is just as safe as encrypted credentials for storing secrets.

Reality: secrets.yml stores secrets in plain text, risking exposure if committed. Encrypted credentials encrypt secrets, protecting them even in version control.

Why it matters: Using secrets.yml can accidentally expose passwords, causing security breaches.

Quick: Do you think changing environment files affects a running Rails app immediately? Commit to yes or no.

Common Belief: Editing environment configuration files changes app behavior instantly without restart.

Reality: Rails loads environment files only at boot. Changes require restarting the app to take effect.

Why it matters: Expecting instant changes can lead to confusion and wasted debugging time.

Quick: Do you think all environment files must have the same settings? Commit to yes or no.

Common Belief: All environment files should have identical settings to avoid bugs.

Reality: Each environment file is meant to have different settings tailored to its purpose, like debugging in development and caching in production.

Why it matters: Copying settings blindly can cause performance issues or security risks.

Expert Zone

1

Encrypted credentials support multiple environments by using separate files or keys, allowing fine-grained secret management.

2

Environment variables can be overridden at runtime by process managers or container orchestrators, enabling dynamic config without code changes.

3

Rails 7 introduced credentials:edit with multi-environment support, improving secret management workflows.

When NOT to use

Avoid using environment configuration files for user-specific or frequently changing data; use databases or caches instead. For very complex config, consider external config services or gems like RailsConfig.

Production Patterns

In production, apps use environment variables set by the hosting platform (like Heroku config vars) combined with encrypted credentials for secrets. Deployment scripts ensure RAILS_ENV is set correctly and secrets are managed securely.

Connections

12-Factor App Methodology

Builds-on

Understanding environment configuration files helps implement the 12-Factor principle of strict separation of config from code, improving app portability and security.

Operating System Environment Variables

Underlying mechanism

Knowing how OS environment variables work clarifies how Rails accesses config and why setting them correctly is crucial for app behavior.

Cryptography

Security principle

Encrypted credentials rely on cryptography to protect secrets, showing how security concepts apply directly to app configuration.

Common Pitfalls

#1 Hardcoding secrets in code files

Wrong approach:

DATABASE_PASSWORD = 'mypassword123'
# used directly in code

Correct approach:

DATABASE_PASSWORD = ENV['DATABASE_PASSWORD']
# set in environment variables

Root cause:

Not understanding the risk of exposing secrets and the purpose of environment variables.

#2 Forgetting to restart app after config change

Wrong approach:

# Changed config/environments/production.rb but did not restart
# expecting new settings to apply immediately

Correct approach:

# After changing config/environments/production.rb
# restart the Rails server to apply changes

Root cause:

Misunderstanding that Rails loads config only at boot time.

#3 Committing unencrypted secrets.yml to public repo

Wrong approach:

# secrets.yml with plain text keys committed to GitHub

Correct approach:

# Use config/credentials.yml.enc and keep master key secure
# Do not commit secrets.yml with sensitive data

Root cause:

Lack of awareness about encrypted credentials and security best practices.

Key Takeaways

Environment configuration files let Rails apps behave differently in development, test, and production safely and flexibly.

Sensitive data should never be hardcoded but stored securely using environment variables and encrypted credentials.

Rails loads environment files and secrets only at startup, so changes require restarting the app to take effect.

Proper environment configuration is essential for secure, maintainable, and reliable Rails applications.

Understanding these files helps you avoid common security mistakes and deployment problems.