# Prepare secrets and keys

> Generate deployment keys for a new instance and preserve the keys an existing instance depends on.

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](/en/self-hosting/simple-or-full-auth).

> **Existing instance**
>
> Keep its existing keys. Replacing a key is a rotation operation with data and session consequences, not a way to repair a missing configuration file. Restore missing values from your backup before proceeding.

## 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:

```sh
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:

```sh
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](/en/install/verify). 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.

## Related

* [Environment variables](/en/reference/environment-variables)
* [Configure authentication](/en/configure/authentication)