Backups & encryption key rotation
Protect EDDYTOR_ENCRYPTION_KEY, back up the right things, and understand why key rotation is a blast-radius reset.
The single most important thing to protect is EDDYTOR_ENCRYPTION_KEY - the
master key for every stored secret. Lose it and those secrets are unrecoverable;
use the wrong one and the server won't boot.
What to back up
| Deployment | Back up |
|---|---|
| Docker Compose | .env (holds EDDYTOR_ENCRYPTION_KEY, EDDYTOR_API_KEY_SECRET, DB + bundled-store creds). |
| Kubernetes | the eddytor-secrets Secret. |
| Both | Postgres - snapshot before every upgrade (migrations are forward-only). |
Heads up
A wrong or missing
EDDYTOR_ENCRYPTION_KEY fails server
boot with secret decrypt failed. Restore the correct key from your backup -
there is no recovery without it.Why key rotation is a blast-radius reset
The secret store is stateless - the handle is the ciphertext. There's no per-secret revocation: the only way to invalidate stored secrets is to rotate the master key, which invalidates every ciphertext at once. Treat rotation as a deliberate blast-radius reset, not routine hygiene.
Rotation runbook
- Generate a new key:
openssl rand -base64 32. - Schedule a maintenance window.
- For each user / org, re-enter the secrets - re-link OAuth providers, re-create storage credentials, re-add AI credentials. There is no scriptable migration: by design, the old key can't decrypt under the new master.
- Swap
EDDYTOR_ENCRYPTION_KEYand restart all replicas. - Old handles in the DB now fail to decrypt and surface as
provider_reauth_required(or similar) - users re-enter on next use.