Environment variables

Each Compose stack has a matching template in deploy/compose. Copy one template to .env, then run Compose from that directory with --env-file .env.

Stack	Template	Compose file
Caddy	.env.caddy	docker-compose.caddy.yml
Direct HTTP	.env.compose	docker-compose.yml
Traefik	.env.traefik	docker-compose.traefik.yml

Required secrets

Variable	Purpose	Guidance
JWT_SECRET	Signs session JWTs	Generate with openssl rand -hex 32. Changing it signs users out.
DB_PASSWORD	PostgreSQL account password	Generate with openssl rand -hex 16. Keep it in sync with the existing database volume.

DANGER

The templates contain development placeholders. Replace both secrets before the first public start and do not commit .env.

Database

Variable	Default	Purpose
DB_DATABASE	bearicorn	PostgreSQL database name
DB_USERNAME	bearicorn	PostgreSQL role used by the app
DB_PASSWORD	bearicorn in the template	PostgreSQL role password; replace it
DB_SCHEMA	public	PostgreSQL schema

Changing database identity values after the postgres_data volume is initialized does not rewrite the existing role or database. Treat those changes as a database migration, not a routine configuration edit.

Common application settings

Variable	Default	Purpose
TZ	UTC	Container timezone
EXPO_NOTIFICATIONS	false	Enables Expo push-notification sending when explicitly added to .env

The current Compose files pass EXPO_NOTIFICATIONS to the application even though the checked-in templates omit it. Leave it disabled unless the mobile notification flow is configured and tested.

Direct HTTP

Variable	Default	Purpose
APP_PORT	8080	Host port published to the application container

Keep this port private when an existing HTTPS proxy fronts the Direct stack.

Caddy

Variable	Default	Purpose
CADDY_SITE_ADDRESS	localhost	Exact hostname Caddy serves
CADDY_HTTP_PORT	8080	Internal Caddy listener; do not change independently
CADDY_HTTPS_PORT	8443	Internal Caddy listener; do not change independently

The Compose file maps public ports 80 and 443 to the two internal listeners. Changing only an internal value breaks that mapping.

APP_PORT appears in .env.caddy but is not consumed by docker-compose.caddy.yml.

Traefik

Variable	Default	Purpose
TRAEFIK_HOST	localhost	Exact hostname matched by the routers
TRAEFIK_ACME_EMAIL	[email protected]	Certificate-registration contact
TRAEFIK_DASHBOARD_PORT	8081	Host binding for the insecure dashboard API

For this repository's Traefik stack, set TRAEFIK_DASHBOARD_PORT=127.0.0.1:8081 so the dashboard is reachable only through a local or SSH-tunneled connection.

Inspect the resolved configuration

Before starting, render the Compose configuration and check for unexpected placeholders:

docker compose --env-file .env -f docker-compose.caddy.yml config

Replace the file name for Direct HTTP or Traefik.