Configuration

Configuration

All configuration for the Compose stack lives in a single .env file next to docker-compose.yml. .env.example is the template; .env itself is gitignored.

Variables read from .env

These are the only variables docker-compose.yml interpolates. A variable written with Compose's :? syntax has no default — Compose refuses to start and prints the message shown if it is empty or missing.

Variable	Default	Required	Effect
DB_PASSWORD	none	Yes	Password for the reportmate Postgres role. Used twice: as POSTGRES_PASSWORD on postgres, and inside the DATABASE_URL given to api. Changing it after first start does not change the password already stored in the volume.
API_INTERNAL_SECRET	none	Yes	Shared secret the dashboard sends to the API to authenticate its own server-side calls. Set on both api and web from this one value; they must match.
REPORTMATE_PASSPHRASE	none	Yes	Passphrase agents present when posting data. Set on both api and web. The API accepts a comma-separated list here, which is how you rotate without downtime.
NEXTAUTH_SECRET	none	Yes	Session-signing secret for the dashboard's NextAuth layer.
REPORTMATE_TAG	latest	No	Image tag for both ghcr.io/reportmate/web and ghcr.io/reportmate/reportmate-api. latest is the only tag both images carry; to pin versions, edit the image: lines. See Upgrading.
DEMO_MODE	true	No	Passed to web as NEXT_PUBLIC_DEMO_MODE. Has no effect on the published web image, which has demo mode compiled off; see Demo mode is fixed at build time.
PUBLIC_URL	http://localhost:3000	No	The dashboard's public origin. Passed to api as CORS_ORIGINS, so it decides which browser origin may call the API cross-origin.
PUBLIC_API_URL	http://localhost:8000	No	The API's public origin. Passed to web as NEXT_PUBLIC_API_BASE_URL. The dashboard reads that only as a fallback when API_BASE_URL is empty, which this stack never leaves it, so in practice it changes nothing.

Values fixed in the Compose file

These are hard-coded in docker-compose.yml and are not driven by .env. To change one, edit the Compose file.

Service	Variable	Value	Effect
postgres	POSTGRES_DB	reportmate	Database name
postgres	POSTGRES_USER	reportmate	Role name
api	DATABASE_URL	postgresql://reportmate:${DB_PASSWORD}@postgres:5432/reportmate	Assembled from DB_PASSWORD; points at the in-network Postgres container
api	DB_SSL	"false"	Disables TLS to Postgres. Correct here — the container-to-container connection has no TLS.
web	NODE_ENV	production	Next.js production runtime
web	API_BASE_URL	http://api:8000	Server-side API base; stays inside the Compose network

Enabling real sign-in

The published dashboard always requires sign-in, and nothing in this stack configures an identity provider for it. The Entra ID variables are read by the dashboard image but are not present in .env.example or in docker-compose.yml — you add them to the web service's environment: block (and to .env) yourself:

Variable	Effect
AZURE_AD_CLIENT_ID	Application (client) id of the app registration
AZURE_AD_CLIENT_SECRET	Client secret for that registration
AZURE_AD_TENANT_ID	Directory (tenant) id
NEXTAUTH_URL	The dashboard's own public URL, e.g. https://reportmate.example.com. NextAuth builds callback URLs from this, so it must match the redirect URI on the app registration.

The dashboard image also reads AUTH_PROVIDERS, DEFAULT_AUTH_PROVIDER, ALLOWED_DOMAINS, GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET. Those are outside what this repo configures; see reportmate-app-web for their semantics.

Kiosk displays

The dashboard supports wall displays that stay signed in without a person's account. It reads KIOSK_TOKENS: a comma-separated list of label:token or bare token entries, each token at least 16 characters. Opening /kiosk?token=<token> on the dashboard exchanges a listed token for a read-only viewer session and redirects to the kiosk home page set in Settings (or to an explicit &next=<path>). Removing a token from the list ends that display's session. The route needs NEXTAUTH_SECRET, which the stack already sets.

KIOSK_TOKENS is not in .env.example or docker-compose.yml. Add it to the web service's environment: block and to .env to use kiosk displays.

Optional API settings

The API image reads further optional variables that this stack leaves at their image defaults, including RATE_LIMIT_PER_MINUTE, RATE_LIMIT_IP_PER_MINUTE, DB_POOL_MIN, DB_POOL_MAX, MAX_DECOMPRESSED_BODY_BYTES, INGEST_FAILURES_RETENTION_DAYS, OIDC_JWKS_URI and OIDC_ROLE_SCOPE_MAP. Add any of them to the api service's environment: block to change them; see reportmate-api for their meaning and defaults.

Demo mode is fixed at build time

Next.js compiles NEXT_PUBLIC_* references into the application when the image is built, on the server as well as in the browser bundle. The published ghcr.io/reportmate/web image is built from the reportmate-app-web Dockerfile with its default NEXT_PUBLIC_DEMO_MODE=false, so the sign-in check and the read-only settings guard are compiled with demo mode off. Setting DEMO_MODE in .env cannot turn it back on.

To evaluate without an identity provider, build the dashboard image yourself with demo mode on. From a clone of reportmate-app-web:

docker build --build-arg NEXT_PUBLIC_DEMO_MODE=true -t reportmate-web:demo .

Then point the web service's image: line in docker-compose.yml at reportmate-web:demo. A demo-mode dashboard skips sign-in entirely and refuses settings writes, so keep it off any network you do not control.

Secret generation

Any long random string works. One per secret:

openssl rand -hex 24

The appliance image does exactly this on first boot when no .env is present — see Appliance Image.