diff --git a/README.md b/README.md index 6deef47..c7bce0f 100644 --- a/README.md +++ b/README.md @@ -191,17 +191,24 @@ This ensures the main branch always contains clean, tested, working code. Environment variables: -| Variable | Description | Default | -| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -| `PORT` | HTTP listen port | 8080 | -| `UPAAS_DATA_DIR` | Data directory for SQLite and keys | `./data` (local dev only — use absolute path for Docker) | -| `UPAAS_HOST_DATA_DIR` | Host path for `UPAAS_DATA_DIR` (when running in container) | _(none — must be set to an absolute path)_ | -| `UPAAS_DOCKER_HOST` | Docker socket path | unix:///var/run/docker.sock | -| `UPAAS_PLAINTEXT_HTTP` | Set when µPaaS is reached over plain HTTP (no TLS-terminating proxy in front) so CSRF origin checks use `http://`. Leave unset behind a TLS-terminating reverse proxy. | false | -| `UPAAS_DEBUG` | Enable debug logging | false | -| `UPAAS_SENTRY_DSN` | Sentry error reporting DSN | "" | -| `UPAAS_METRICS_USERNAME` | Basic auth for /metrics | "" | -| `UPAAS_METRICS_PASSWORD` | Basic auth for /metrics | "" | +| Variable | Description | Default | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | +| `PORT` | HTTP listen port. `UPAAS_PORT` is also read and wins when both are set. | 8080 | +| `UPAAS_DATA_DIR` | Directory for the SQLite database, session key, builds and deployment logs. Deploys need it to be an absolute path unless `UPAAS_HOST_DATA_DIR` is set. | `./data` (the Docker image sets `/var/lib/upaas`) | +| `UPAAS_HOST_DATA_DIR` | Host path of `UPAAS_DATA_DIR`, needed when upaas runs in a container so the bind mounts it passes to Docker point at the right host directory. When set, it must be absolute, or upaas refuses to start. | the value of `UPAAS_DATA_DIR` | +| `UPAAS_DOCKER_HOST` | Docker daemon address | unix:///var/run/docker.sock | +| `UPAAS_PLAINTEXT_HTTP` | Set when µPaaS is reached over plain HTTP (no TLS-terminating proxy in front) so CSRF origin checks use `http://`. Leave unset behind a TLS-terminating reverse proxy. | false | +| `UPAAS_DEBUG` | Enable debug logging. Also sends the session cookie without the `Secure` flag. | false | +| `UPAAS_SENTRY_DSN` | Read but not used: upaas sends nothing to Sentry | "" | +| `UPAAS_METRICS_USERNAME` | When set, `/metrics` is served behind basic auth with this username. When unset, there is no `/metrics`. | "" | +| `UPAAS_METRICS_PASSWORD` | Basic auth password for `/metrics` | "" | +| `UPAAS_MAINTENANCE_MODE` | Only shown as `maintenanceMode` in the `/health` response; it blocks nothing | false | +| `UPAAS_SESSION_SECRET` | Key that signs the session and CSRF cookies. When unset, a random key is generated once and kept in `$UPAAS_DATA_DIR/session.key`. | "" | +| `UPAAS_CORS_ORIGINS` | Comma-separated origins allowed to make cross-origin requests with cookies. When unset, no CORS headers are sent. | "" | + +The Docker client also reads the standard `DOCKER_API_VERSION`, +`DOCKER_CERT_PATH` and `DOCKER_TLS_VERIFY` variables; `UPAAS_DOCKER_HOST`, which +has a default, always overrides `DOCKER_HOST`. ## Running with Docker @@ -230,10 +237,11 @@ HOST_DATA_DIR=/srv/upaas/data ``` Other settings from [Configuration](#configuration) go in the same file, except -`PORT` and `UPAAS_DATA_DIR`: the compose file sets them to 8080 and -`/var/lib/upaas`, overriding `.env`, to match its port mapping, healthcheck and -data directory mount. Then run `docker compose up -d` from the repo root; -`docker compose ps` shows the container as healthy once `/health` answers. +`PORT`, `UPAAS_PORT` and `UPAAS_DATA_DIR`: the compose file sets both port +settings to 8080 and `UPAAS_DATA_DIR` to `/var/lib/upaas`, overriding `.env`, to +match its port mapping, healthcheck and data directory mount. Then run +`docker compose up -d` from the repo root; `docker compose ps` shows the +container as healthy once `/health` answers. **Important**: `HOST_DATA_DIR` **must** be an **absolute path** on the host. It is bind-mounted into the container and passed as `UPAAS_HOST_DATA_DIR` so that diff --git a/TODO.md b/TODO.md index 0fabf94..ff43640 100644 --- a/TODO.md +++ b/TODO.md @@ -20,6 +20,18 @@ regress. # Completed Steps +- 2026-09-29: `docker-compose.yml` now sets `UPAAS_PORT` to 8080 as well as + `PORT`, since upaas reads `UPAAS_PORT` first and a `UPAAS_PORT` in `.env` made + it listen away from the port mapping and healthcheck; the README's Compose + section names both (#230). + +- 2026-09-29: The README Configuration table now lists every setting upaas + reads, adding `UPAAS_MAINTENANCE_MODE`, `UPAAS_SESSION_SECRET` and + `UPAAS_CORS_ORIGINS`, and gives the real default and effect of each: + `UPAAS_PORT` wins over `PORT`, `UPAAS_HOST_DATA_DIR` falls back to + `UPAAS_DATA_DIR`, `UPAAS_DEBUG` drops the session cookie's `Secure` flag, and + `UPAAS_SENTRY_DSN` is not used (#229). + - 2026-09-28: The README Configuration table now names `UPAAS_DEBUG`, `UPAAS_SENTRY_DSN`, `UPAAS_METRICS_USERNAME` and `UPAAS_METRICS_PASSWORD`, the names upaas actually reads (the unprefixed names it listed were ignored), and diff --git a/docker-compose.yml b/docker-compose.yml index 51a31cf..f33a2b6 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -7,9 +7,11 @@ services: # Every line of .env is passed to upaas as an environment variable. env_file: .env environment: - # Overrides any PORT in .env, so upaas listens where the port mapping - # and healthcheck below expect it. + # Override any PORT or UPAAS_PORT in .env, so upaas listens where the + # port mapping and healthcheck below expect it. Both are set because + # upaas reads UPAAS_PORT first. PORT: "8080" + UPAAS_PORT: "8080" # Overrides any UPAAS_DATA_DIR in .env, so the database stays on the # HOST_DATA_DIR mount below instead of inside the container. UPAAS_DATA_DIR: /var/lib/upaas