| Priority |
Environment |
.gitignoreit? |
Notes |
|
development |
test |
production |
|
|
| highest |
.env.development.local |
.env.test.local |
.env.production.local |
Yes |
Environment-specific local overrides |
| 2nd |
.env.local |
N/A |
.env.local |
Yes |
Local overrides |
| 3rd |
.env.development |
.env.test |
.env.production |
No |
Shared environment-specific variables |
| last |
.env |
.env |
.env |
Maybe |
Shared for all environments |
These files are loaded 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, or need to customize the loading process, you can do so at the top of `application.rb`
```ruby
# config/application.rb
Bundler.require(*Rails.groups)
# Load .env.local in test
Dotenv::Rails.files.unshift(".env.local") if ENV["RAILS_ENV"] == "test"
module YourApp
class Application < Rails::Application
# ...
end
end
```
Available options:
* `Dotenv::Rails.files` - list of files to be loaded, in order of precedence.
* `Dotenv::Rails.overwrite` - Overwrite existing `ENV` variables with contents of `.env*` files
* `Dotenv::Rails.logger` - The logger to use for dotenv's logging. Defaults to `Rails.logger`
* `Dotenv::Rails.autorestore` - Enable or disable [autorestore](#autorestore-in-tests)
### Multi-line values
Multi-line values with line breaks must be surrounded with double quotes.
```shell
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
HkVN9...
...
-----END DSA PRIVATE KEY-----"
```
Prior to 3.0, dotenv would replace `\n` in quoted strings with a newline, but that behavior is deprecated. To use the old behavior, set `DOTENV_LINEBREAK_MODE=legacy` before any variables that include `\n`:
```shell
DOTENV_LINEBREAK_MODE=legacy
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nHkVN9...\n-----END DSA PRIVATE KEY-----\n"
```
### Command Substitution
You need to add the output of a command in one of your variables? Simply add it with `$(your_command)`:
```shell
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 unquoted or double-quoted values.
```shell
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.
```shell
PASSWORD='pas$word'
```
### Comments
Comments may be added to your file as such:
```shell
# This is a comment
SECRET_KEY=YOURSECRETKEYGOESHERE # comment
SECRET_HASH="something-with-a-#-hash"
```
### Exports
For compatability, you may also add `export` in front of each line so you can `source` the file in bash:
```shell
export S3_BUCKET=YOURS3BUCKET
export SECRET_KEY=YOURSECRETKEYGOESHERE
```
### Required Keys
If a particular configuration value is required but not set, it's appropriate to raise an error.
To require configuration keys:
```ruby
# config/initializers/dotenv.rb
Dotenv.require_keys("SERVICE_APP_ID", "SERVICE_KEY", "SERVICE_SECRET")
```
If any of the configuration keys above are not set, your application will raise an error during initialization. This method is preferred because it prevents runtime errors in a production application due to improper configuration.
### Parsing
To parse a list of env files for programmatic inspection without modifying the ENV:
```ruby
Dotenv.parse(".env.local", ".env")
# => {'S3_BUCKET' => 'YOURS3BUCKET', 'SECRET_KEY' => 'YOURSECRETKEYGOESHERE', ...}
```
This method returns a hash of the ENV var name/value pairs.
### Templates
You can use the `-t` or `--template` flag on the dotenv cli to create a template of your `.env` file.
```console
$ dotenv -t .env
```
A template will be created in your working directory named `{FILENAME}.template`. So in the above example, it would create a `.env.template` file.
The template will contain all the environment variables in your `.env` file but with their values set to the variable names.
```shell
# .env
S3_BUCKET=YOURS3BUCKET
SECRET_KEY=YOURSECRETKEYGOESHERE
```
Would become
```shell
# .env.template
S3_BUCKET=S3_BUCKET
SECRET_KEY=SECRET_KEY
```
## 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](https://github.com/puppetlabs/puppet) or [Chef](https://github.com/chef/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.