From 96609fc32835e1124be114bc79dcc2993ecda54d Mon Sep 17 00:00:00 2001 From: Nicolas Meienberger Date: Mon, 20 Apr 2026 19:47:14 +0200 Subject: [PATCH] docs: update configuration to mention APP_SECRET_FILE --- apps/docs/content/docs/configuration.mdx | 34 +++++++++++++++++++++- apps/docs/content/docs/troubleshooting.mdx | 7 +++-- 2 files changed, 37 insertions(+), 4 deletions(-) diff --git a/apps/docs/content/docs/configuration.mdx b/apps/docs/content/docs/configuration.mdx index e2c38564..fada487f 100644 --- a/apps/docs/content/docs/configuration.mdx +++ b/apps/docs/content/docs/configuration.mdx @@ -12,12 +12,17 @@ Zerobyte is configured through environment variables and Docker Compose settings | Variable | Description | Example | |----------|-------------|---------| | `BASE_URL` | The URL where Zerobyte will be accessed. Controls cookie security and CORS behavior. | `http://localhost:4096` or `https://zerobyte.example.com` | -| `APP_SECRET` | Random secret key (32+ characters) used to encrypt sensitive data in the database. Generate with `openssl rand -hex 32`. | `94bad46e...c66e25d5c2b` | +| `APP_SECRET` | Random secret key (32+ characters) used to encrypt sensitive data in the database. Generate with `openssl rand -hex 32`. Set this or `APP_SECRET_FILE`, but not both. | `94bad46e...c66e25d5c2b` | +| `APP_SECRET_FILE` | Alternative to `APP_SECRET`. Path to a file containing the app secret, useful with Docker or Kubernetes secrets. Set this or `APP_SECRET`, but not both. | `/run/secrets/app_secret` | Never share or commit your `APP_SECRET`. If you lose it, encrypted data (credentials stored for volumes and repositories) cannot be recovered. + + Zerobyte reads the contents of `APP_SECRET_FILE`, trims surrounding whitespace and newlines, and applies the same 32-256 character requirement as `APP_SECRET`. + + ### Recommended | Variable | Description | Default | @@ -37,6 +42,33 @@ Zerobyte is configured through environment variables and Docker Compose settings | `RCLONE_CONFIG_DIR` | Path to the rclone config directory inside the container. | `/root/.config/rclone` | | `PROVISIONING_PATH` | Path to a JSON file with operator-managed repositories and volumes to sync at startup. | (none) | +## Using APP_SECRET_FILE + +If you prefer not to place the app secret directly in `environment:`, mount it as a file and point `APP_SECRET_FILE` at that path. + +```yaml docker-compose.yml +services: + zerobyte: + environment: + - BASE_URL=https://zerobyte.example.com + - APP_SECRET_FILE=/run/secrets/app_secret + secrets: + - app_secret + +secrets: + app_secret: + file: ./secrets/app_secret.txt +``` + +Generate the secret file with: + +```bash +mkdir -p ./secrets +openssl rand -hex 32 > ./secrets/app_secret.txt +``` + +Do not set `APP_SECRET` at the same time. Zerobyte will fail to start if both are configured. + ## Docker Compose Settings ### Volume Mounts diff --git a/apps/docs/content/docs/troubleshooting.mdx b/apps/docs/content/docs/troubleshooting.mdx index a4378aa7..edc8c25f 100644 --- a/apps/docs/content/docs/troubleshooting.mdx +++ b/apps/docs/content/docs/troubleshooting.mdx @@ -27,9 +27,10 @@ docker logs -f zerobyte ## Container Won't Start 1. Check logs: `docker compose logs zerobyte` -2. Verify `APP_SECRET` is set and at least 32 characters -3. Ensure `/var/lib/zerobyte` exists and has correct permissions -4. Verify port 4096 is not already in use: `netstat -tuln | grep 4096` +2. Verify exactly one of `APP_SECRET` or `APP_SECRET_FILE` is set +3. If using `APP_SECRET_FILE`, ensure the file exists inside the container, is readable, and contains a 32-256 character secret +4. Ensure `/var/lib/zerobyte` exists and has correct permissions +5. Verify port 4096 is not already in use: `netstat -tuln | grep 4096` ### Permission Issues