dotenv

Shim to load environment variables from .env into ENV in development.

Storing configuration in the environment is one of the tenets of a twelve-factor app. Anything that is likely to change between deployment environments–such as resource handles for databases or credentials for external services–should be extracted from the code into environment variables.

But it is not always practical to set environment variables on development machines or continuous integration servers where multiple projects are run. dotenv loads variables from a .env file into ENV when the environment is bootstrapped.

Installation

Rails

Add this line to the top of your application's Gemfile:

gem'dotenv-rails',groups:[:development,:test]

And then execute:

$ bundle

Note on load order

dotenv is initialized in your Rails app during the before_configuration callback, which is fired when the Application constant is defined in config/application.rb with class Application < Rails::Application. If you need it to be initialized sooner, you can manually call Dotenv::Railtie.load.

Command Substitution

You need to add the output of a command in one of your variables? Simply add it with $(your_command):

DATABASE_URL="postgres://$(whoami)@localhost/my_database"

Variable Substitution

You need to add the value of another variable in one of your variables? You can reference the variable with ${VAR} or often just $VAR in unqoted or double-quoted values.

DATABASE_URL="postgres://${USER}@localhost/my_database"

If a value contains a $ and it is not intended to be a variable, wrap it in single quotes.

PASSWORD='pas$word'

Comments

Comments may be added to your file as such:

# This is a comment
SECRET_KEY=YOURSECRETKEYGOESHERE # comment
SECRET_HASH="something-with-a-#-hash"

Frequently Answered Questions

Can I use dotenv in production?

dotenv was originally created to load configuration variables into ENV in development. There are typically better ways to manage configuration in production environments - such as /etc/environment managed by Puppet or Chef, heroku config, etc.

However, some find dotenv to be a convenient way to configure Rails applications in staging and production environments, and you can do that by defining environment-specific files like .env.production or .env.test.

If you use this gem to handle env vars for multiple Rails environments (development, test, production, etc.), please note that env vars that are general to all environments should be stored in .env. Then, environment specific env vars should be stored in .env.<that environment's name>.

What other .env* files can I use?

dotenv-rails will load the following files, starting from the bottom. The first value set (or those already defined in the environment) take precedence:

Should I commit my .env file?

Credentials should only be accessible on the machines that need access to them. Never commit sensitive information to a repository that is not needed by every development machine and server.

Personally, I prefer to commit the .env file with development-only settings. This makes it easy for other developers to get started on the project without compromising credentials for other environments. If you follow this advice, make sure that all the credentials for your development environment are different from your other deployments and that the development credentials do not have access to any confidential data.

Why is it not overriding existing ENV variables?

By default, it won't overwrite existing environment variables as dotenv assumes the deployment environment has more knowledge about configuration than the application does. To overwrite existing environment variables you can use Dotenv.overload.