docs: environment variable encryption at rest and backup key requirements

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.
 </Callout>
 
+## 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.
+
+<Callout type="warn">
+  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.
+</Callout>
+
+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).
+

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/
 </Callout>
+
+## 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.

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
+- 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.
+
+<Callout type="warn">
+  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.
+</Callout>
+
+Existing installations upgrade seamlessly: previously stored plaintext values keep working and are encrypted the next time they are saved.