diff --git a/apps/docs/content/docs/core/backups.mdx b/apps/docs/content/docs/core/backups.mdx index 7233134b..23b9845b 100644 --- a/apps/docs/content/docs/core/backups.mdx +++ b/apps/docs/content/docs/core/backups.mdx @@ -46,6 +46,24 @@ During restoration, Dokploy will: After restoration is complete, you may need to log in again. If necessary, you can restart Traefik to ensure all services are properly configured. +## Encryption Key + +Environment variables are stored encrypted in the Dokploy database, using a key derived from your `BETTER_AUTH_SECRET` (or a dedicated `ENCRYPTION_KEY` if you configured one). + +By default, web server backups have **Include encryption key** enabled: the backup contains the derived encryption keys (never the raw secrets), so restoring on a brand-new server works out of the box — environment variables decrypt automatically and are re-encrypted with the new server's key as they are saved. + + + With **Include encryption key** enabled, anyone with access to the backup file can decrypt the environment variables inside it. Protect your S3 destination accordingly, or disable the toggle for stricter security. + + +If you disable **Include encryption key**, a backup alone is not enough — the restoring server must use the same secret. Store your `BETTER_AUTH_SECRET` / `ENCRYPTION_KEY` somewhere safe (for example, a password manager). To retrieve it from a running server installed via the install script: + +```bash +docker exec $(docker ps -qf name=dokploy.1) cat /run/secrets/dokploy_auth_secret +``` + +If the secrets don't match when restoring, Dokploy still works, but environment variables will show as `enc:v1:...` strings until you re-enter them manually — or set `ENCRYPTION_KEY` on the new server to the old server's `BETTER_AUTH_SECRET` value, which produces the same derived key. + ## Post-Restoration Steps After restoring a backup, especially if you're restoring to a different server, consider the following: @@ -58,3 +76,5 @@ After restoring a backup, especially if you're restoring to a different server, 2. If you're using domain names instead of IPs for Git providers, no additional configuration is needed. +3. If you restored to a server with a different `BETTER_AUTH_SECRET` / `ENCRYPTION_KEY`, environment variables will be unreadable — see [Encryption Key](#encryption-key). + diff --git a/apps/docs/content/docs/core/troubleshooting.mdx b/apps/docs/content/docs/core/troubleshooting.mdx index f83df9e3..d8ec8443 100644 --- a/apps/docs/content/docs/core/troubleshooting.mdx +++ b/apps/docs/content/docs/core/troubleshooting.mdx @@ -778,3 +778,24 @@ If you are using Dokploy Cloud, you don't need to worry about this, our team wil Start using Dokploy Cloud https://app.dokploy.com/ + +## Environment Variables Empty or Showing `enc:v1:` Values + +Environment variables are stored encrypted in the Dokploy database, using a key derived from `BETTER_AUTH_SECRET` (or a dedicated `ENCRYPTION_KEY`). Two symptoms indicate a key mismatch: + +- Environment variable fields in the UI show `enc:v1:...` strings instead of your values +- Deployments finish successfully but the container starts with **no environment variables** + +Check the Dokploy logs for this message to confirm: + +``` +Failed to decrypt an encrypted column +``` + +Common causes: + +1. **`BETTER_AUTH_SECRET` changed** after the values were encrypted — for example, a fresh install with a restored database, or a rotated secret. Restore the original secret, or set `ENCRYPTION_KEY` to the old `BETTER_AUTH_SECRET` value (it produces the same derived key), or re-enter the affected variables. + +2. **Multiple Dokploy components with different secrets** — if you run any additional Dokploy service that reads the same database (for example, a separate deployments worker, schedules, or monitoring service), **every component must use exactly the same `BETTER_AUTH_SECRET` and `ENCRYPTION_KEY`**. A component with different keys cannot decrypt the variables and may deploy services with an empty environment. + +Your data is not lost in either case — the encrypted values remain intact in the database. Once the keys are aligned, **redeploy the affected services** so the environment variables are injected again. diff --git a/apps/docs/content/docs/core/variables.mdx b/apps/docs/content/docs/core/variables.mdx index 1f29254f..b9b90a37 100644 --- a/apps/docs/content/docs/core/variables.mdx +++ b/apps/docs/content/docs/core/variables.mdx @@ -109,4 +109,24 @@ DATABASE_URL=postgresql://${{DATABASE_USER}}:${{DATABASE_PASSWORD}}@service-data - Use shared variables for credentials and configurations that repeat across services - Keep descriptive variable names -- Document the purpose of each variable for easier maintenance \ No newline at end of file +- Document the purpose of each variable for easier maintenance + +## Encryption at Rest + +Environment variables (including build args and build secrets) are encrypted with AES-256-GCM before being stored in the Dokploy database. Database dumps and backups only contain ciphertext. + +By default, the encryption key is derived from your `BETTER_AUTH_SECRET` — no configuration is needed. Optionally, you can set a dedicated key to decouple data encryption from the auth secret: + +```bash +ENCRYPTION_KEY=your-random-secret +# or, using Docker secrets: +ENCRYPTION_KEY_FILE=/run/secrets/dokploy_encryption_key +``` + +With a dedicated `ENCRYPTION_KEY` set, you can rotate `BETTER_AUTH_SECRET` without affecting stored variables. Values encrypted before the switch remain readable and are re-encrypted with the new key the next time they are saved. + + + Back up your `BETTER_AUTH_SECRET` (or `ENCRYPTION_KEY`) together with your database backups. Without the original secret, encrypted values cannot be recovered — they will show as `enc:v1:...` strings until re-entered manually. See [Backups](/docs/core/backups#encryption-key) for details. + + +Existing installations upgrade seamlessly: previously stored plaintext values keep working and are encrypted the next time they are saved. \ No newline at end of file