Merge pull request #47738 from p8/railties/thor-usage-titles
Use indentation for dividing sections in USAGE files
This commit is contained in:
Rafael Mendonça França
GitHub
commit
89bd41201a
@ -1,78 +1,73 @@
|
||||
=== Storing Encrypted Credentials in Source Control
|
||||
Description:
|
||||
The Rails `credentials` commands provide access to encrypted credentials,
|
||||
so you can safely store access tokens, database passwords, and the like
|
||||
safely inside the app without relying on a mess of ENVs.
|
||||
|
||||
The Rails `credentials` commands provide access to encrypted credentials,
|
||||
so you can safely store access tokens, database passwords, and the like
|
||||
safely inside the app without relying on a mess of ENVs.
|
||||
This also allows for atomic deploys: no need to coordinate key changes
|
||||
to get everything working as the keys are shipped with the code.
|
||||
|
||||
This also allows for atomic deploys: no need to coordinate key changes
|
||||
to get everything working as the keys are shipped with the code.
|
||||
Setup:
|
||||
Applications after Rails 5.2 automatically have a basic credentials file generated
|
||||
that just contains the secret_key_base used by MessageVerifiers/MessageEncryptors, like the ones
|
||||
signing and encrypting cookies.
|
||||
|
||||
=== Setup
|
||||
For applications created prior to Rails 5.2, we'll automatically generate a new
|
||||
credentials file in `config/credentials.yml.enc` the first time you run `<%= executable(:edit) %>`.
|
||||
If you didn't have a master key saved in `config/master.key`, that'll be created too.
|
||||
|
||||
Applications after Rails 5.2 automatically have a basic credentials file generated
|
||||
that just contains the secret_key_base used by MessageVerifiers/MessageEncryptors, like the ones
|
||||
signing and encrypting cookies.
|
||||
Don't lose this master 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
|
||||
credentials.
|
||||
|
||||
For applications created prior to Rails 5.2, we'll automatically generate a new
|
||||
credentials file in `config/credentials.yml.enc` the first time you run `<%= executable(:edit) %>`.
|
||||
If you didn't have a master key saved in `config/master.key`, that'll be created too.
|
||||
Don't commit the key! Add `config/master.key` to your source control's
|
||||
ignore file. If you use Git, Rails handles this for you.
|
||||
|
||||
Don't lose this master 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
|
||||
credentials.
|
||||
Rails also looks for the master key in `ENV["RAILS_MASTER_KEY"]`, in case that
|
||||
is easier to manage. You could set `RAILS_MASTER_KEY` in a deployment
|
||||
configuration, or you could prepend it to your server's start command like so:
|
||||
|
||||
Don't commit the key! Add `config/master.key` to your source control's
|
||||
ignore file. If you use Git, Rails handles this for you.
|
||||
RAILS_MASTER_KEY="very-secret-and-secure" server.start
|
||||
|
||||
Rails also looks for the master key in `ENV["RAILS_MASTER_KEY"]`, in case that
|
||||
is easier to manage. You could set `RAILS_MASTER_KEY` in a deployment
|
||||
configuration, or you could prepend it to your server's start command like so:
|
||||
If `ENV["RAILS_MASTER_KEY"]` is present, it takes precedence over
|
||||
`config/master.key`.
|
||||
|
||||
RAILS_MASTER_KEY="very-secret-and-secure" server.start
|
||||
Set up Git to Diff Credentials:
|
||||
Rails provides `<%= executable(:diff) %> --enroll` to instruct Git to call
|
||||
`<%= executable(:diff) %>` when `git diff` is run on a credentials file.
|
||||
|
||||
If `ENV["RAILS_MASTER_KEY"]` is present, it takes precedence over
|
||||
`config/master.key`.
|
||||
Running the command enrolls the project such that all credentials files use the
|
||||
"rails_credentials" diff driver in .gitattributes.
|
||||
|
||||
=== Set up Git to Diff Credentials
|
||||
Additionally since Git requires the driver itself to be set up in a config file
|
||||
that isn't tracked Rails automatically ensures it's configured when running
|
||||
`<%= executable(:edit) %>`.
|
||||
|
||||
Rails provides `<%= executable(:diff) %> --enroll` to instruct Git to call
|
||||
`<%= executable(:diff) %>` when `git diff` is run on a credentials file.
|
||||
Otherwise each co-worker would have to run enable manually, including on each new
|
||||
repo clone.
|
||||
|
||||
Running the command enrolls the project such that all credentials files use the
|
||||
"rails_credentials" diff driver in .gitattributes.
|
||||
To disenroll from this feature, run `<%= executable(:diff) %> --disenroll`.
|
||||
|
||||
Additionally since Git requires the driver itself to be set up in a config file
|
||||
that isn't tracked Rails automatically ensures it's configured when running
|
||||
`<%= executable(:edit) %>`.
|
||||
Editing Credentials:
|
||||
This will open a temporary file in `$EDITOR` with the decrypted contents to edit
|
||||
the encrypted credentials.
|
||||
|
||||
Otherwise each co-worker would have to run enable manually, including on each new
|
||||
repo clone.
|
||||
When the temporary file is next saved the contents are encrypted and written to
|
||||
`config/credentials.yml.enc` while the file itself is destroyed to prevent credentials
|
||||
from leaking.
|
||||
|
||||
To disenroll from this feature, run `<%= executable(:diff) %> --disenroll`.
|
||||
Environment Specific Credentials:
|
||||
The `credentials` command supports passing an `--environment` option to create an
|
||||
environment specific override. That override will take precedence over the
|
||||
global `config/credentials.yml.enc` file when running in that environment. So:
|
||||
|
||||
=== Editing Credentials
|
||||
<%= executable(:edit) %> --environment development
|
||||
|
||||
This will open a temporary file in `$EDITOR` with the decrypted contents to edit
|
||||
the encrypted credentials.
|
||||
will create `config/credentials/development.yml.enc` with the corresponding
|
||||
encryption key in `config/credentials/development.key` if the credentials file
|
||||
doesn't exist.
|
||||
|
||||
When the temporary file is next saved the contents are encrypted and written to
|
||||
`config/credentials.yml.enc` while the file itself is destroyed to prevent credentials
|
||||
from leaking.
|
||||
In addition to that, the default credentials lookup paths can be overridden through
|
||||
`config.credentials.content_path` and `config.credentials.key_path`.
|
||||
|
||||
=== Environment Specific Credentials
|
||||
|
||||
The `credentials` command supports passing an `--environment` option to create an
|
||||
environment specific override. That override will take precedence over the
|
||||
global `config/credentials.yml.enc` file when running in that environment. So:
|
||||
|
||||
<%= executable(:edit) %> --environment development
|
||||
|
||||
will create `config/credentials/development.yml.enc` with the corresponding
|
||||
encryption key in `config/credentials/development.key` if the credentials file
|
||||
doesn't exist.
|
||||
|
||||
In addition to that, the default credentials lookup paths can be overridden through
|
||||
`config.credentials.content_path` and `config.credentials.key_path`.
|
||||
|
||||
Just as with `config/master.key`, `ENV["RAILS_MASTER_KEY"]` takes precedence
|
||||
over any environment specific or specially configured key files.
|
||||
Just as with `config/master.key`, `ENV["RAILS_MASTER_KEY"]` takes precedence
|
||||
over any environment specific or specially configured key files.
|
||||
|
||||
@ -1,28 +1,23 @@
|
||||
=== Storing Encrypted Files in Source Control
|
||||
Description:
|
||||
The Rails `encrypted` commands provide access to encrypted files or configurations.
|
||||
See the `Rails.application.encrypted` documentation for using them in your app.
|
||||
|
||||
The Rails `encrypted` commands provide access to encrypted files or configurations.
|
||||
See the `Rails.application.encrypted` documentation for using them in your app.
|
||||
Encryption Keys:
|
||||
By default, Rails looks for the encryption key in `ENV["RAILS_MASTER_KEY"]` or
|
||||
`config/master.key`, but that lookup can be overridden with `--key`:
|
||||
|
||||
=== Encryption Keys
|
||||
<%= executable(:edit) %> config/encrypted_file.yml.enc --key config/encrypted_file.key
|
||||
|
||||
By default, Rails looks for the encryption key in `ENV["RAILS_MASTER_KEY"]` or
|
||||
`config/master.key`, but that lookup can be overridden with `--key`:
|
||||
Don't commit the key! Add it to your source control's ignore file. If you use
|
||||
Git, Rails handles this for you.
|
||||
|
||||
<%= executable(:edit) %> config/encrypted_file.yml.enc --key config/encrypted_file.key
|
||||
Examples:
|
||||
To edit or create an encrypted file use:
|
||||
|
||||
Don't commit the key! Add it to your source control's ignore file. If you use
|
||||
Git, Rails handles this for you.
|
||||
<%= executable(:edit) %> config/encrypted_file.yml.enc
|
||||
|
||||
=== Editing Files
|
||||
This opens a temporary file in `$EDITOR` with the decrypted contents for editing.
|
||||
|
||||
To edit or create an encrypted file use:
|
||||
To print the decrypted contents of an encrypted file use:
|
||||
|
||||
<%= executable(:edit) %> config/encrypted_file.yml.enc
|
||||
|
||||
This opens a temporary file in `$EDITOR` with the decrypted contents for editing.
|
||||
|
||||
=== Viewing Files
|
||||
|
||||
To print the decrypted contents of an encrypted file use:
|
||||
|
||||
<%= executable(:show) %> config/encrypted_file.yml.enc
|
||||
<%= executable(:show) %> config/encrypted_file.yml.enc
|
||||
|
||||
@ -1,21 +1,22 @@
|
||||
Description:
|
||||
The Rails `runner` allows running Ruby code in the context of your application.
|
||||
|
||||
Examples:
|
||||
Run `puts Rails.env` after loading the app:
|
||||
|
||||
Run `puts Rails.env` after loading the app:
|
||||
<%= executable %> 'puts Rails.env'
|
||||
|
||||
<%= executable %> 'puts Rails.env'
|
||||
Run the Ruby file located at `path/to/filename.rb` after loading the app:
|
||||
|
||||
Run the Ruby file located at `path/to/filename.rb` after loading the app:
|
||||
<%= executable %> path/to/filename.rb
|
||||
|
||||
<%= executable %> path/to/filename.rb
|
||||
|
||||
Run the Ruby script read from stdin after loading the app:
|
||||
|
||||
<%= executable %> -
|
||||
Run the Ruby script read from stdin after loading the app:
|
||||
|
||||
<%= executable %> -
|
||||
<% unless Gem.win_platform? -%>
|
||||
You can also use the runner command as a shebang line for your executables:
|
||||
|
||||
#!/usr/bin/env <%= File.expand_path(executable) %>
|
||||
You can also use the runner command as a shebang line for your executables:
|
||||
|
||||
Product.all.each { |p| p.price *= 2 ; p.save! }
|
||||
#!/usr/bin/env <%= File.expand_path(executable) %>
|
||||
Product.all.each { |p| p.price *= 2 ; p.save! }
|
||||
<% end -%>
|
||||
|
||||
@ -1,66 +1,61 @@
|
||||
=== ** DEPRECATED **
|
||||
Description:
|
||||
** DEPRECATED **
|
||||
Rails 5.2 has introduced a new `credentials` API that replaces Rails secrets.
|
||||
Please use the Rails `credentials` commands instead.
|
||||
Run `bin/rails credentials:help` for more information.
|
||||
|
||||
Rails 5.2 has introduced a new `credentials` API that replaces Rails secrets.
|
||||
Please use the Rails `credentials` commands instead.
|
||||
Run `bin/rails credentials:help` for more information.
|
||||
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.
|
||||
|
||||
=== Storing Encrypted Secrets in Source Control
|
||||
Setup:
|
||||
Run `<%= executable(:setup) %>` to opt in and generate the `config/secrets.yml.key`
|
||||
and `config/secrets.yml.enc` files.
|
||||
|
||||
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.
|
||||
The latter contains all the keys to be encrypted while the former holds the
|
||||
encryption key.
|
||||
|
||||
=== Setup
|
||||
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.
|
||||
|
||||
Run `<%= executable(:setup) %>` to opt in and generate the `config/secrets.yml.key`
|
||||
and `config/secrets.yml.enc` files.
|
||||
Rails also looks for the key in `ENV["RAILS_MASTER_KEY"]` if that's easier to
|
||||
manage.
|
||||
|
||||
The latter contains all the keys to be encrypted while the former holds the
|
||||
encryption key.
|
||||
You could prepend that to your server's start command like this:
|
||||
|
||||
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_MASTER_KEY="im-the-master-now-hahaha" server.start
|
||||
|
||||
Rails also looks for the key in `ENV["RAILS_MASTER_KEY"]` if that's easier to
|
||||
manage.
|
||||
The `config/secrets.yml.enc` has much the same format as `config/secrets.yml`:
|
||||
|
||||
You could prepend that to your server's start command like this:
|
||||
production:
|
||||
secret_key_base: so-secret-very-hidden-wow
|
||||
payment_processing_gateway_key: much-safe-very-gaedwey-wow
|
||||
|
||||
RAILS_MASTER_KEY="im-the-master-now-hahaha" server.start
|
||||
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.
|
||||
|
||||
The `config/secrets.yml.enc` has much the same format as `config/secrets.yml`:
|
||||
Additionally, Rails won't read encrypted secrets out of the box even if you have
|
||||
the key. Add this:
|
||||
|
||||
production:
|
||||
secret_key_base: so-secret-very-hidden-wow
|
||||
payment_processing_gateway_key: much-safe-very-gaedwey-wow
|
||||
config.read_encrypted_secrets = true
|
||||
|
||||
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.
|
||||
to the environment you'd like to read encrypted secrets. `<%= executable(:setup) %>`
|
||||
inserts this into the production environment by default.
|
||||
|
||||
A `shared:` top level key is also supported such that any keys there is merged
|
||||
into the other environments.
|
||||
Editing Secrets:
|
||||
After `<%= executable(:setup) %>`, run `<%= executable(:edit) %>`.
|
||||
|
||||
Additionally, Rails won't read encrypted secrets out of the box even if you have
|
||||
the key. Add this:
|
||||
That command opens a temporary file in `$EDITOR` with the decrypted contents of
|
||||
`config/secrets.yml.enc` to edit the encrypted secrets.
|
||||
|
||||
config.read_encrypted_secrets = true
|
||||
|
||||
to the environment you'd like to read encrypted secrets. `<%= executable(:setup) %>`
|
||||
inserts this into the production environment by default.
|
||||
|
||||
=== Editing Secrets
|
||||
|
||||
After `<%= executable(:setup) %>`, run `<%= executable(: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.
|
||||
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.
|
||||
|
||||
@ -1,9 +1,10 @@
|
||||
You can run a single test by appending a line number to a filename:
|
||||
Examples:
|
||||
You can run a single test by appending a line number to a filename:
|
||||
|
||||
<%= executable %> test/models/user_test.rb:27
|
||||
<%= executable %> test/models/user_test.rb:27
|
||||
|
||||
You can run multiple files and directories at the same time:
|
||||
You can run multiple files and directories at the same time:
|
||||
|
||||
<%= executable %> test/controllers test/integration/login_test.rb
|
||||
<%= executable %> test/controllers test/integration/login_test.rb
|
||||
|
||||
By default test failures and errors are reported inline during a run.
|
||||
By default test failures and errors are reported inline during a run.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user