Prepare secrets and keys

Това съдържание все още не е достъпно на вашия език.

Prepare the keys for a new deployment before accepting real secrets or accounts.

Prerequisites

Access to the deployment’s secret manager or protected environment configuration.
A choice of simple or full authentication.

Steps

1. Generate the keys

Every instance needs SECRET. Full mode also uses three independent keys: AUTH_SECRET, ARGON2_SECRET and ACCOUNT_ID_SECRET. Generate all three before launch, even though the application can start without ARGON2_SECRET.

In a source installation, bin/install generates these keys in .env. To run that step yourself, use the application’s key task from the application directory:

bundle exec rake ots:secrets

The task generates SECRET, the keys derived from it, the three independent keys and a FEDERATION_SECRET passphrase. It keeps an existing SECRET and any independent value that is already set, unless you pass FORCE=1 to regenerate SECRET.

For a container deployment or a secret manager, generate each value yourself and save the output directly in your secret manager:

openssl rand -hex 64   # SECRET
openssl rand -hex 32   # run once each for AUTH_SECRET, ARGON2_SECRET and ACCOUNT_ID_SECRET

Do not reuse one generated value for several variables or commit the values to Git. ACCOUNT_ID_SECRET must be at least 32 bytes.

2. Supply the keys to the application

Set SECRET in the environment supplied by your deployment system. For full mode, also set AUTH_SECRET, ARGON2_SECRET and ACCOUNT_ID_SECRET. Give every application process that needs the same data the appropriate matching keys.

SECRET is the root for derived keys. None of the three independent keys can be recovered from it. ARGON2_SECRET is a password pepper: set it before the first password account is created. Adding, changing or removing it later invalidates every existing password hash, and there is no transition setting for it.

3. Back up before launch

Keep recoverable copies separately from the running containers. Include keys in your disaster-recovery procedure alongside datastore and account-database backups.

Record which deployment and datastore each backup belongs to. Restoring data without its matching SECRET can leave the site running while older secrets are unreadable. Preserve the independent full-mode keys as well; recovering SECRET does not reconstruct them.

Verify it worked

Start the instance using your installation procedure and check for missing-key errors. Complete Verify your install. Confirm that the next container replacement or service restart will receive the same values.

Also check for [secret_verifier] SECRET MISMATCH. The default SECRET_VERIFIER_MODE=warn logs a mismatch and continues booting; enforce stops boot on a mismatch and off skips the check. A healthy-looking new secret does not establish that restored ciphertext uses the right key. On an unintended mismatch, restore the matching key or correct the datastore URL before accepting traffic. Do not adopt a new verifier merely to silence the warning: adoption records the current key but does not recover old ciphertext.

Full-mode failures have a different cause when AUTH_SECRET or ACCOUNT_ID_SECRET is missing. Production authentication requires both, with at least 32 bytes for ACCOUNT_ID_SECRET; an unset RACK_ENV resolves to production. Inspect the application log even if Compose created the containers successfully.

Rotation is a separate task

SECRET_PREVIOUS decrypts older ciphertext and AUTH_OLD_SECRET supports an authentication-key transition. These have different purposes and retention requirements. Rotate one key at a time; do not rotate by replacing all keys together.