Skip to content

Configuration, networking and TLS

The production Compose deployment reads .env alongside docker-compose.prod.yml for interpolation and passes it to the server. Protect the file with mode 0600, restrict access, and never commit or share its contents. Use a secret manager to provision sensitive values where possible. Process environment values can override values from the file; check both when diagnosing configuration.

Set these values privately for the production Compose deployment:

Setting Purpose
GHCR_OWNER, GHCR_REPO Registry image owner and repository prefix. The deployment script requires GHCR_OWNER; GHCR_REPO defaults to bugfence.
BUGFENCE_SESSION_SECRET Random session signing secret, at least 32 characters.
BUGFENCE_INTEGRATIONS_SECRET Separate random secret, at least 32 characters, for stored integration credentials. Retain the matching secret for recovery.
BUGFENCE_ADMIN_PATH Random console path segment, 16–128 letters, digits, hyphens or underscores.
BUGFENCE_ADMIN_BOOTSTRAP_CODE Separate random bootstrap code, at least 24 characters, usable while no administrator exists. Compose requires it to remain set after the initial claim.
DOMAIN_NAME, BUGFENCE_PUBLIC_URL Application hostname and public HTTPS URL. Set the public URL explicitly for links and authentication callbacks.

Generate each secret independently with a cryptographically secure generator. Production rejects missing, weak or development-default session and integration secrets, and invalid admin values. Never expose private keys, bootstrap codes, database credentials or integration secrets in browser code.

Without BUGFENCE_DATABASE_URL, the server uses its persistent data volume as a file store. Run only one server process per data directory. For multiple instances, configure a shared PostgreSQL database and the same session and integration secrets on each instance.

The optional postgres profile is for a database on the Compose host. Set BUGFENCE_POSTGRES_PASSWORD, a matching BUGFENCE_DATABASE_URL, and BUGFENCE_DATABASE_SSL=disable for that private, non-TLS container connection. Production defaults to requiring TLS, so an unset SSL setting does not work with the bundled non-TLS database. For a database on another host, use a protected connection with BUGFENCE_DATABASE_SSL=require and certificate validation. Preserve the server data volume as well: it can contain a storage spill journal during database outages.

Select one ingress profile with COMPOSE_PROFILES: caddy or tunnel. Add postgres as a comma-separated profile if using the bundled database.

  • Caddy: publishes host ports 80 and 443 and routes application requests to the internal services. CADDY_TLS_MODE=acme uses ACME; origin uses a Cloudflare Origin CA certificate and key supplied to the mounted certificate directory. Configure DNS, certificate validation and firewall rules for your topology. An Origin CA certificate is for a Cloudflare-proxied origin, not direct browser trust.
  • Tunnel: the connector makes outbound connections without publishing host ports. Configure the tunnel’s public application hostname to reach http://dashboard:5000 and, if used, a separate demo hostname to reach http://demo:3000. Supply its token securely; the Compose file can read cloudflared.env. The supplied Compose configuration also passes the application .env to the tunnel container, so treat that container as having access to its secrets.

The Compose server sets BUGFENCE_TRUST_PROXY=true. Restrict access so requests cannot bypass trusted ingress, and ensure every proxy path overwrites forwarded client IP, host and protocol headers. Configure exact BUGFENCE_CORS_ORIGINS for management clients on other origins; ingestion has separate CORS behavior. Confirm that the chosen public URL and proxy routing match your authentication callbacks.

Cloudflare Pages publishes static documentation; it is not the application ingress or a replacement for the Caddy or Tunnel configuration.