Add docker-compose.yml for deploying upaas (closes #223)

The compose file builds the image from this repo, mounts the Docker
socket and HOST_DATA_DIR (passed to upaas as UPAAS_HOST_DATA_DIR),
reads settings from .env, and restarts unless stopped. The port is
published on 127.0.0.1 only, for a TLS-terminating proxy in front, and
UPAAS_PLAINTEXT_HTTP is left unset. A healthcheck against /health uses
the runtime image's busybox wget.

The README's plain-HTTP Compose example becomes a short deploy section
that points at the file. .env is added to .dockerignore so settings are
not copied into the build.

Model: opus-5-5

.dockerignore

@@ -1,4 +1,5 @@
 .git
+.env
 bin/
 .editorconfig
 .vscode/

README.md

@@ -219,39 +219,28 @@ This recipe serves plain HTTP, so `UPAAS_PLAINTEXT_HTTP=true` is required for
 setup and every other form to pass the CSRF origin check. Behind a
 TLS-terminating reverse proxy, drop that line.
 
-### Docker Compose
+### Deploying with Docker Compose
 
-```yaml
-services:
-    upaas:
-        build: .
-        restart: unless-stopped
-        ports:
-            - "8080:8080"
-        volumes:
-            - /var/run/docker.sock:/var/run/docker.sock
-            - ${HOST_DATA_DIR}:/var/lib/upaas
-        environment:
-            - UPAAS_HOST_DATA_DIR=${HOST_DATA_DIR}
-            # Set when serving plain HTTP (no TLS-terminating proxy); drop behind one
-            - UPAAS_PLAINTEXT_HTTP=true
-            # Optional: uncomment to enable debug logging
-            # - DEBUG=true
-            # Optional: Sentry error reporting
-            # - SENTRY_DSN=https://...
-            # Optional: Prometheus metrics auth
-            # - METRICS_USERNAME=prometheus
-            # - METRICS_PASSWORD=secret
+[`docker-compose.yml`](docker-compose.yml) builds the image from this repo and
+runs it with the Docker socket and the data directory mounted. It reads its
+settings from a `.env` file next to it, which needs at least:
+
+```bash
+HOST_DATA_DIR=/srv/upaas/data
 ```
 
-**Important**: You **must** set `HOST_DATA_DIR` to an **absolute path** on the
-host before running `docker compose up`. This value is bind-mounted into the
-container and passed as `UPAAS_HOST_DATA_DIR` so that Docker bind mounts during
-builds resolve correctly. Relative paths (e.g. `./data`) will break container
-builds because the Docker daemon resolves paths relative to the host, not the
-container.
+Other settings from [Configuration](#configuration) go in the same file. Then
+run `docker compose up -d` from the repo root; `docker compose ps` shows the
+container as healthy once `/health` answers.
 
-Example: `HOST_DATA_DIR=/srv/upaas/data docker compose up -d`
+**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
+Docker bind mounts during builds resolve correctly. Relative paths (e.g.
+`./data`) will break container builds because the Docker daemon resolves paths
+relative to the host, not the container.
+
+The port is published on `127.0.0.1:8080` only, for a TLS-terminating reverse
+proxy in front of it. Leave `UPAAS_PLAINTEXT_HTTP` unset behind that proxy.
 
 Apps are built with BuildKit, so the stages of a multi-stage build are kept in
 Docker's build cache rather than as untagged images. Docker Engine 28.2 and

TODO.md

@@ -20,6 +20,11 @@ regress.
 
 # Completed Steps
 
+- 2026-09-28: Added `docker-compose.yml` for deploying upaas: settings from
+  `.env`, the port published on `127.0.0.1` only for a TLS proxy in front, and a
+  healthcheck against `/health`; the README's plain-HTTP Compose example is
+  replaced by a short deploy section (#223).
+
 - 2026-09-23: Apps are now built with BuildKit, so the stages of a multi-stage
   build stay in Docker's size-limited build cache instead of piling up as
   untagged images; build progress is still written to the deployment log as

docker-compose.yml

@@ -0,0 +1,24 @@
+# Runs upaas. Put settings in .env next to this file; see "Deploying with
+# Docker Compose" in README.md.
+services:
+  upaas:
+    build: .
+    restart: unless-stopped
+    # Every line of .env is passed to upaas as an environment variable.
+    env_file: .env
+    environment:
+      # The Docker daemon resolves app bind mounts on the host, so upaas must
+      # know the host path of its data directory.
+      UPAAS_HOST_DATA_DIR: ${HOST_DATA_DIR:?set HOST_DATA_DIR in .env to an absolute host path}
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - ${HOST_DATA_DIR:?set HOST_DATA_DIR in .env to an absolute host path}:/var/lib/upaas
+    # Loopback only, for a TLS-terminating reverse proxy in front. Leave
+    # UPAAS_PLAINTEXT_HTTP unset behind that proxy.
+    ports:
+      - "127.0.0.1:8080:8080"
+    healthcheck:
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:8080/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3