aboutsummaryrefslogtreecommitdiffstats
path: root/railties/lib/rails/commands/secrets/USAGE
blob: 96e322fe915651a3cff324a8a0e27d19d2d8c743 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
=== Storing Encrypted Secrets in Source Control

The Rails `secrets` commands helps encrypting secrets to slim a production
environment's `ENV` hash. It's also useful for atomic deploys: no need to
coordinate key changes to get everything working as the keys are shipped
with the code.

=== Setup

Run `bin/rails secrets:setup` to opt in and generate the `config/secrets.yml.key`
and `config/secrets.yml.enc` files.

The latter contains all the keys to be encrypted while the former holds the
encryption key.

Don't lose the key! Put it in a password manager your team can access.
Should you lose it no one, including you, will be able to access any encrypted
secrets.
Don't commit the key! Add `config/secrets.yml.key` to your source control's
ignore file. If you use Git, Rails handles this for you.

Rails also looks for the key in `ENV["RAILS_MASTER_KEY"]` if that's easier to
manage.

You could prepend that to your server's start command like this:

   RAILS_MASTER_KEY="im-the-master-now-hahaha" server.start


The `config/secrets.yml.enc` has much the same format as `config/secrets.yml`:

   production:
     secret_key_base: so-secret-very-hidden-wow
     payment_processing_gateway_key: much-safe-very-gaedwey-wow

But that's where the similarities between `secrets.yml` and `secrets.yml.enc`
end, e.g. no keys from `secrets.yml` will be moved to `secrets.yml.enc` and
be encrypted.

A `shared:` top level key is also supported such that any keys there is merged
into the other environments.

Additionally, Rails won't read encrypted secrets out of the box even if you have
the key. Add this:

   config.read_encrypted_secrets = true

to the environment you'd like to read encrypted secrets. `bin/rails secrets:setup`
inserts this into the production environment by default.

=== Editing Secrets

After `bin/rails secrets:setup`, run `bin/rails secrets:edit`.

That command opens a temporary file in `$EDITOR` with the decrypted contents of
`config/secrets.yml.enc` to edit the encrypted secrets.

When the temporary file is next saved the contents are encrypted and written to
`config/secrets.yml.enc` while the file itself is destroyed to prevent secrets
from leaking.