[bug]: Self-hosted production install (v1.3.1): missing env vars on proxy/live services, plus setup.sh/production docs gap

[wverbeeck]

Is there an existing issue for this?

• I have searched the existing issues

Current behavior

Did a from-scratch self-hosted install following the production docker-compose.yml (deliberately not using setup.sh/docker-compose-local.yml, since those are dev-oriented). Two services (proxy and live) failed to start due to missing environment variables that the compose file itself never wires up.

ISSUE 1: proxy crash-loops. Its environment: block only sets FILE_SIZE_LIMIT and BUCKET_NAME. But apps/proxy/Caddyfile.ce references {$SITE_ADDRESS}, {$CERT_EMAIL}, {$CERT_ACME_DNS}, {$TRUSTED_PROXIES} - none of which are passed to the container (no env_file, not in environment:). Since {$SITE_ADDRESS} has no fallback default, it resolves to empty, which Caddy parses as an unintended second keyless global-config block:

Error: adapting config using caddyfile: server block without any key is global configuration, and if used, it must be first

Fix applied locally: added the missing vars to proxy's environment: block (SITE_ADDRESS, CERT_EMAIL, CERT_ACME_CA, CERT_ACME_DNS, TRUSTED_PROXIES).

Sub-issue: once fixed, Caddy's trusted_proxies static directive also requires space-separated CIDRs in TRUSTED_PROXIES, not comma-separated - neither .env.example nor docs mention this format requirement.

ISSUE 2: live crash-loops. It has NO environment: or env_file: at all in docker-compose.yml. Fails immediately with:

Invalid environment variables: API_BASE_URL (Required), LIVE_SERVER_SECRET_KEY (Required)

Fix applied locally: gave live an env_file pointing at apps/api/.env (which already defines LIVE_SERVER_SECRET_KEY), and added API_BASE_URL="http://api:8000" there.

ISSUE 3 (documentation): setup.sh only targets docker-compose-local.yml and doesn't cover the production path. apps/api/.env.example has no SECRET_KEY at all, and LIVE_SERVER_SECRET_KEY is just the placeholder "secret-key" - for production these must be generated manually with no docs pointing this out. The single-proxy production architecture (path-based routing via *_BASE_PATH) also isn't obviously connected to apps/api/.env.example's dev-style localhost:PORT defaults.

Checked v1.4.0-rc1/rc2 release notes before filing - neither mentions anything related to the above, so these appear to still be live issues as of the latest available release.

Related issues (searched before filing):

• [bug]: Caddy fails to start in version v0.28.0 (Docker Compose) #7565 (Caddy fails to start, v0.28.0) - same general symptom category (proxy/Caddy won't start), but an older version with a different specific error (no logs generated at all, vs. our specific Caddyfile parse error) - likely a different root cause, not a duplicate.
• • [security] Insecure trusted proxy configuration #8862 ([security] Insecure trusted proxy configuration, closed) - about the default TRUSTED_PROXIES=0.0.0.0/0 being too permissive. Related to our TRUSTED_PROXIES finding but doesn't cover the comma-vs-space CIDR format issue, or the more basic fact that the proxy service doesn't receive TRUSTED_PROXIES (or SITE_ADDRESS/CERT_EMAIL/CERT_ACME_DNS) at all in the current docker-compose.yml.
    Suggested fix for proxy specifically: since [security] Insecure trusted proxy configuration #8862 already flagged that TRUSTED_PROXIES needs careful defaults, this seems like a good opportunity to fix both at once - add the five missing variables to proxy's environment: block in docker-compose.yml (as shown above), document that trusted_proxies static expects space-separated CIDRs, and consider defaulting TRUSTED_PROXIES to something more restrictive than 0.0.0.0/0 in .env.example per [security] Insecure trusted proxy configuration #8862's original recommendation.

Deployment stack (generic, for context):

• Proxmox VE host
• • Unprivileged Debian 12 LXC container running Docker/Docker Compose
• • • NAS-backed persistent storage, mounted via a Proxmox-managed disk image (not a raw NFS bind-mount into the container - ran into permission issues doing it that way, since unprivileged-container UID-shifting doesn't translate cleanly through an NFS-backed bind mount; routing through a proper disk-image mount point on Proxmox's storage layer resolved it)
• • • • No public exposure yet - reached over LAN/private network only, no reverse proxy or TLS layered on top of Plane's own proxy service at this stage

Steps to reproduce

1. Clone Plane at pinned tag v1.3.1, configure .env and apps/api/.env for production (not dev setup.sh)
2. 2. Run docker compose up -d using the production docker-compose.yml
3. 3. Observe proxy and live containers crash-looping on start
4. 4. docker logs proxy shows the Caddyfile parse error above
5. 5. docker logs plane-live shows the missing-env-var error above
      Environment: Debian 12, Docker 29.x, single-host deployment, 4 vCPU / 8GB RAM (note: the space frontend build was OOM-killed at 4GB during the initial build - worth mentioning 8GB as a more realistic build-time minimum).

Also worth noting as a general data point (not a bug): docker compose up had to be retried 6 times before all 18 images built successfully, hitting transient DNS/connectivity failures against four different external services in turn (registry.npmjs.org, pypi.org, proxy.golang.org, Alpine's CDN mirror). None were structural problems on our end (confirmed via direct dig/curl testing) - just ordinary home-network flakiness. BuildKit's layer caching meant each retry made real progress, so the install did complete, but a docs note that this is expected/normal might save less experienced self-hosters some anxiety.

Happy to open separate issues per item if preferred, or provide more logs/detail on any of the above.

Environment

Production

Browser

None

Variant

Self-hosted

Version

v1.3.1

[makeplane]

Synced with Plane Workspace 🔄

[GIT-293] [bug]: Self-hosted production install (v1.3.1): missing env vars on proxy/live services, plus setup.sh/production docs gap

[sjsadowski]

Going to update this with one that is current (v1.4.0) about the docs:
The SECRET_KEY must be changed in plane.env and that is obvious if you scroll down to see it in the envvars; it is NOT obvious if you don't know it's necessary and it is not a documented step here: https://developers.plane.so/self-hosting/methods/docker-compose

[lazyzyf]

Going to update this with one that is current (v1.4.0) about the docs:
The SECRET_KEY must be changed in plane.env and that is obvious if you scroll down to see it in the envvars; it is NOT obvious if you don't know it's necessary and it is not a documented step here: https://developers.plane.so/self-hosting/methods/docker-compose

What is SECRET_KEY?why need to change it? Change it to what?

[lazyzyf]

Going to update this with one that is current (v1.4.0) about the docs:
The SECRET_KEY must be changed in plane.env and that is obvious if you scroll down to see it in the envvars; it is NOT obvious if you don't know it's necessary and it is not a documented step here: https://developers.plane.so/self-hosting/methods/docker-compose

When you say SECRET_KEY do you actually mean LIVE_SERVER_SECRET_KEY?

[sjsadowski]

No, the API container went into a reboot loop and required me to change this in plane.env before starting:

# Secret Key — change this before deploying to production.
# Generate a secure value with: python3 -c "from django.utils.crypto import get_random_secret_key; print(get_random_secret_key())"
# or: openssl rand -hex 32
SECRET_KEY=change-this-key-on-deployment

[lazyzyf]

i already changed the SECRET_KEY in plane.env, but the log still shows this message, is it normal?

[api] | SECURITY: SECRET_KEY is set to a known insecure or placeholder value. This makes your installation vulnerable to session forgery, CSRF bypass, and password-reset token forging. Set a unique SECRET_KEY before deploying to production. Generate one with: python3 -c "from django.utils.crypto import get_random_secret_key; print(get_random_secret_key())"

[sjsadowski]

That's different than the crash-loop I was getting.