Last updated 03 September 2019

Rails has the concept of different environments. By default there is “test”, “development” and “production”. Each environment has its own configuration file in config/environments folder allowing you to specify custom behavior. Rails also exposes Rails.env allowing you to write custom logic inside of your code:

if Rails.env.production?
  # ...
else
  # ...
end

Bundler is environment aware and will allow you to only load certain gems in certain environments:

gem 'rails_12factor', group: "production"

It may be tempting to create another custom environment such as “staging” and create a config/environments/staging.rb and deploy to a Heroku app with RAILS_ENV=staging.

This is not a good practice. Instead we recommend always running in production mode and modifying any behavior by setting your config vars.

Dev/prod parity

Heroku highly recommends keeping your development and production environments as close together as possible. This is called dev/prod parity. We also recommend keeping your staging as close to production as possible. If they are too different, deploying and testing on a staging app does not verify your production instance will work.

Explicit behavior

It is best practice while writing logic involving environment to declare behavior based on only one environment. For example instead of writing:

if !Rails.env.development? && !Rails.env.test?
  # ...

It would be better to write

if Rails.env.production?
  # ...

The behavior difference is subtle yet important. If you introduce a staging environment any custom logic in the Rails.env.production? will not be executed.

In addition to environment-specific code, bundler will not load gems targeted to :production when run in the RAILS_ENV=staging environment.

Setting staging behavior

Code is often written to change configuration based on the environment. For example, you don’t want your staging apps sending out real emails, or using your production S3 bucket. So instead of using Rails.env and a custom staging environment like this:

if Rails.env.staging?
  S3_BUCKET = "my_staging_bucket_name"
end

It would be better to set this through an environment variable:

S3_BUCKET = ENV['MY_BUCKET_NAME']

Doing this avoids the need of a custom environment, and you can still fully control behavior by having a different set of config vars for each app.

The email example mentioned above can be avoided by changing email provider credentials provided they are in environment variables, or even setting your provider to use a “test” mode, for example, you can tell mailgun to not send out emails.

Any configuration you wish to change in config/environments/production.rb can be set from environment variables instead of hardcoded and checked into git.

Locally

Locally you can set these environment variables with a .env file.

Summary

Your “staging” app or any other custom environments should be run with RAILS_ENV=production to minimize differences in behavior. Environment variables should be used to configure your application to achieve different behavior when desired instead of a custom environment.