From 24cd3c43620935ee74006731859eacbc5ebd542b Mon Sep 17 00:00:00 2001 From: Mauricio Siu Date: Fri, 10 Jul 2026 02:49:21 -0600 Subject: [PATCH 1/3] docs: document env variable encryption at rest and backup key requirements --- apps/docs/content/docs/core/backups.mdx | 18 ++++++++++++++++++ apps/docs/content/docs/core/variables.mdx | 22 +++++++++++++++++++++- 2 files changed, 39 insertions(+), 1 deletion(-) diff --git a/apps/docs/content/docs/core/backups.mdx b/apps/docs/content/docs/core/backups.mdx index 7233134b..b2623b3d 100644 --- a/apps/docs/content/docs/core/backups.mdx +++ b/apps/docs/content/docs/core/backups.mdx @@ -46,6 +46,22 @@ 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). A backup alone is not enough to restore them — **the restoring server must use the same secret**. + + + A complete Dokploy backup is the backup file **plus** your `BETTER_AUTH_SECRET` / `ENCRYPTION_KEY`. Store the secret somewhere safe (for example, a password manager) when you set up backups. + + +To retrieve the secret from a running server installed via the install script: + +```bash +docker exec $(docker ps -qf name=dokploy.1) cat /run/secrets/dokploy_auth_secret +``` + +When restoring on a **new server**, set the same secret before restoring. If the secrets don't match, Dokploy still works, but environment variables will show as `enc:v1:...` strings until you re-enter them manually. + ## Post-Restoration Steps After restoring a backup, especially if you're restoring to a different server, consider the following: @@ -58,3 +74,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/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 From 3811b39822713c23b21eea7ec439d3e223fc61c2 Mon Sep 17 00:00:00 2001 From: Mauricio Siu Date: Mon, 13 Jul 2026 04:05:16 -0600 Subject: [PATCH 2/3] docs: reflect include-encryption-key backup option --- apps/docs/content/docs/core/backups.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/apps/docs/content/docs/core/backups.mdx b/apps/docs/content/docs/core/backups.mdx index b2623b3d..23b9845b 100644 --- a/apps/docs/content/docs/core/backups.mdx +++ b/apps/docs/content/docs/core/backups.mdx @@ -48,19 +48,21 @@ After restoration is complete, you may need to log in again. If necessary, you c ## 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). A backup alone is not enough to restore them — **the restoring server must use the same secret**. +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. - A complete Dokploy backup is the backup file **plus** your `BETTER_AUTH_SECRET` / `ENCRYPTION_KEY`. Store the secret somewhere safe (for example, a password manager) when you set up backups. + 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. -To retrieve the secret from a running server installed via the install script: +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 ``` -When restoring on a **new server**, set the same secret before restoring. If the secrets don't match, Dokploy still works, but environment variables will show as `enc:v1:...` strings until you re-enter them manually. +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 From a4bfdcec41402cad151b12d3b846f1863ca0145c Mon Sep 17 00:00:00 2001 From: Mauricio Siu Date: Mon, 13 Jul 2026 23:03:40 -0600 Subject: [PATCH 3/3] docs: troubleshoot encrypted env values and multi-component key mismatch --- .../content/docs/core/troubleshooting.mdx | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) 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.