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

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):

• #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.
• • #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 #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 #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