Merge next into main: UPAAS_ setting names in the README (#228)

On `next`: the README's Configuration table now names the settings upaas actually reads, `UPAAS_DEBUG`, `UPAAS_SENTRY_DSN`, `UPAAS_METRICS_USERNAME` and `UPAAS_METRICS_PASSWORD`, instead of the unprefixed names it ignores (#224). Docs only; no code changes.

For deploying: nothing changes. Anyone who set `DEBUG`, `SENTRY_DSN` or `METRICS_USERNAME`/`METRICS_PASSWORD` as the old table said got no effect and needs the `UPAAS_` names.

The table still leaves out `UPAAS_MAINTENANCE_MODE`, `UPAAS_SESSION_SECRET` and `UPAAS_CORS_ORIGINS`, which upaas also reads.

Model: opus-5-5
Reviewed-on: #228
Co-authored-by: clawbot <35+clawbot@noreply.example.org>

README.md

@@ -191,17 +191,17 @@ This ensures the main branch always contains clean, tested, working code.
 
 Environment variables:
 
-| Variable               | Description                                                                                                                                                            | Default                                                  |
+| Variable                 | Description                                                                                                                                                            | Default                                                  |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
-| `PORT`                 | HTTP listen port                                                                                                                                                       | 8080                                                     |
+| `PORT`                   | HTTP listen port                                                                                                                                                       | 8080                                                     |
-| `UPAAS_DATA_DIR`       | Data directory for SQLite and keys                                                                                                                                     | `./data` (local dev only — use absolute path for Docker) |
+| `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 DATA_DIR (when running in container)                                                                                                                     | _(none — must be set to an absolute path)_               |
+| `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_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_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                                                    |
-| `DEBUG`                | Enable debug logging                                                                                                                                                   | false                                                    |
+| `UPAAS_DEBUG`            | Enable debug logging                                                                                                                                                   | false                                                    |
-| `SENTRY_DSN`           | Sentry error reporting DSN                                                                                                                                             | ""                                                       |
+| `UPAAS_SENTRY_DSN`       | Sentry error reporting DSN                                                                                                                                             | ""                                                       |
-| `METRICS_USERNAME`     | Basic auth for /metrics                                                                                                                                                | ""                                                       |
+| `UPAAS_METRICS_USERNAME` | Basic auth for /metrics                                                                                                                                                | ""                                                       |
-| `METRICS_PASSWORD`     | Basic auth for /metrics                                                                                                                                                | ""                                                       |
+| `UPAAS_METRICS_PASSWORD` | Basic auth for /metrics                                                                                                                                                | ""                                                       |
 
 ## Running with Docker
 
@@ -229,15 +229,17 @@ settings from a `.env` file next to it, which needs at least:
 HOST_DATA_DIR=/srv/upaas/data
 ```
 
-Other settings from [Configuration](#configuration) go in the same file. Then
+Other settings from [Configuration](#configuration) go in the same file, except
-run `docker compose up -d` from the repo root; `docker compose ps` shows the
+`PORT` and `UPAAS_DATA_DIR`: the compose file sets them to 8080 and
-container as healthy once `/health` answers.
+`/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
-Docker bind mounts during builds resolve correctly. Relative paths (e.g.
+Docker bind mounts during builds resolve correctly, because the Docker daemon
-`./data`) will break container builds because the Docker daemon resolves paths
+resolves paths on the host, not in the container. upaas refuses to start when
-relative to the host, not the container.
+`UPAAS_HOST_DATA_DIR` is a relative path such as `./data`.
 
 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.

TODO.md

@@ -20,10 +20,16 @@ regress.
 
 # Completed Steps
 
+- 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
+  the `UPAAS_HOST_DATA_DIR` row refers to `UPAAS_DATA_DIR` (#224).
+
 - 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).
+  replaced by a short deploy section. upaas now refuses to start when
+  `UPAAS_HOST_DATA_DIR` is set to a relative path (#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

docker-compose.yml

@@ -7,6 +7,12 @@ 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.
+      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
       # 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}

internal/config/config.go

@@ -32,6 +32,12 @@ const (
 	filePermissions = 0o600
 )
 
+// errHostDataDirNotAbsolute is returned when UPAAS_HOST_DATA_DIR is set to a
+// relative path, which the Docker daemon cannot resolve for app bind mounts.
+var errHostDataDirNotAbsolute = errors.New(
+	"UPAAS_HOST_DATA_DIR must be an absolute path",
+)
+
 // Params contains dependencies for Config.
 type Params struct {
 	fx.In
@@ -124,6 +130,10 @@ func buildConfig(log *slog.Logger, params *Params) (*Config, error) {
 	dataDir := viper.GetString("DATA_DIR")
 	hostDataDir := viper.GetString("HOST_DATA_DIR")
 
+	if hostDataDir != "" && !filepath.IsAbs(hostDataDir) {
+		return nil, fmt.Errorf("%w, got %q", errHostDataDirNotAbsolute, hostDataDir)
+	}
+
 	if hostDataDir == "" {
 		hostDataDir = dataDir
 	}

internal/config/config_test.go

@@ -0,0 +1,33 @@
+package config //nolint:testpackage // tests unexported buildConfig
+
+import (
+	"errors"
+	"log/slog"
+	"testing"
+)
+
+func TestBuildConfigRejectsRelativeHostDataDir(t *testing.T) {
+	t.Setenv("UPAAS_HOST_DATA_DIR", "./data")
+	setupViper("upaas")
+
+	_, err := buildConfig(slog.Default(), &Params{})
+	if !errors.Is(err, errHostDataDirNotAbsolute) {
+		t.Fatalf("expected errHostDataDirNotAbsolute, got %v", err)
+	}
+}
+
+func TestBuildConfigHostDataDirDefaultsToDataDir(t *testing.T) {
+	t.Setenv("UPAAS_DATA_DIR", "./data")
+	t.Setenv("UPAAS_HOST_DATA_DIR", "")
+	t.Setenv("UPAAS_SESSION_SECRET", "test-secret")
+	setupViper("upaas")
+
+	cfg, err := buildConfig(slog.Default(), &Params{})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	if cfg.HostDataDir != "./data" {
+		t.Errorf("expected HostDataDir ./data, got %q", cfg.HostDataDir)
+	}
+}