Environment variables

Every setting each repo reads, where it's set, and whether it's secret.

Operators set none of these to get started. Everything below has a safe default; the operator-facing list is in the monorepo’s README and .env.example. Never commit a .env.

Operator settings (`.env` next to `docker-compose.yml`)

Setting	Default	What it does
`PORT`	`8080`	The port on the server
`BIND`	`127.0.0.1`	Who can reach it: `127.0.0.1` this machine only, `0.0.0.0` every network
`COMPOSE_PROFILES`		`https` (Caddy), `updater` (one-click updates), or both comma-separated
`DOMAIN`		The domain Caddy serves with HTTPS
`ADMIN_DATABASE_URL`		Your own Postgres or Supabase, as its owner (start with `--scale db=0`)
`OXR_APP_ID`		Open Exchange Rates on your key instead of the free source
`JOBS_HOUR`	`19`	Daily jobs, as an hour in UTC (19 = 02:00 in Vietnam), for those the admin hasn’t given a time on Server admin
`UPDATE_CHECK`	`on`	`off`: never ask GitHub for the newest release
`PROJECT_SITE_URL`	`https://waterflow-app.net`	The project’s website: What’s new on Server admin opens its changelog. Empty: the GitHub release instead

Google Cloud Run

Set on the Cloud Run service (Run it on Google Cloud Run), not in .env: docker-compose.yml doesn’t pass it.

Setting	Default	What it does
`RUN_JOBS`	`on`	`off`: the server doesn’t run the daily jobs; a scheduled job runs `python -m app.launch jobs` instead

Inside the `waterflow` container

Set by app/launch.py or the image; a developer sees them in backend/scripts/dev.sh.

Variable	Set by	What
`DATABASE_URL`	launcher	The API’s login (`api_login`); the API gets no other database URL
`PURGE_DATABASE_URL`, `FX_DATABASE_URL`	launcher	The jobs’ logins
`BACKUP_DATABASE_URL`	launcher	The owner, for `pg_dump`
`BACKUP_DIR`, `PURGE_LOG`	launcher	`/backups`, `/backups/purged_accounts.jsonl`
`SECRETS_DIR`	default `/secrets`	The database passwords (made on first start; on Cloud Run, `db_logins.json` is a mounted secret)
`SERVER_STARTED_AT`	launcher	When this start began: Server admin ignores an update result from before it
`UPDATES_DIR`	default `/updates`	The updater’s request, status and heartbeat files
`WEB_DIR`	image	The built web app (`/srv/web`)
`UPDATE_REPO`	default `LeeMinNguyeen/waterflow`	Where releases are checked
`DEV_RELOAD`	development only	uvicorn `--reload`
`PG_DUMP`	optional	Which `pg_dump` the backup uses
`LAUNCHER_PID`	launcher	Which process the API stops after a restore is asked for

Tests

Variable	Value
`TEST_ADMIN_URL`	`postgresql+psycopg://postgres@localhost:5499/postgres`

Web (build time, public)

Everything here ends up in the browser bundle, so only public values. None are needed.

Variable	Value
`VITE_APP_STORE_URL`, `VITE_PLAY_STORE_URL`	Empty until the mobile app ships
`WATERFLOW_API`	`npm run dev` only: where Vite proxies `/v1` (default `http://127.0.0.1:8000`); the proxy sends `X-Forwarded-Host`, so the API sees the web app as its own

Landing (build time, public)

Variable	Value
`PUBLIC_SITE_URL`	`https://waterflow-app.net` (locally `http://localhost:4321`)
`PUBLIC_REPO_URL`	`https://github.com/LeeMinNguyeen/waterflow`
`PUBLIC_DONATE_URL`	Optional; the donate button appears only when set

GitHub (CI)

Repo	Variables	Secrets
waterflow		none: releases are made with the workflow’s own token
waterflow-landing	`PUBLIC_SITE_URL`, `PUBLIC_REPO_URL`, `PUBLIC_DONATE_URL`, `DEPLOY_ENABLED`	`CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_ACCOUNT_ID`