From c8c5f0071fad7d756b12a35f3529af5c0670b085 Mon Sep 17 00:00:00 2001 From: Marco Date: Mon, 20 Apr 2026 17:33:07 +0200 Subject: [PATCH] feat: Enhance Docker deployment configuration with parameterized environment variables and detailed README --- README.Docker.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ docker-compose.yml | 23 +++++++++++++++++------ 2 files changed, 62 insertions(+), 6 deletions(-) diff --git a/README.Docker.md b/README.Docker.md index aab278f..7cfede9 100644 --- a/README.Docker.md +++ b/README.Docker.md @@ -8,6 +8,51 @@ Quick run (Docker Engine required): 2. App will be available on host port 8002 -> container 8080 (http://localhost:8002). +Production deployment: + +- Put deployment values in a `.env` file next to `docker-compose.yml` or export them in the shell before running Docker Compose. +- The base compose file is now parameterized for host port, persisted storage path, image tag, auth mode, seeded user credentials, allowed hosts, and healthcheck timings. +- For a direct production deployment, define at least `WORKTRACKER_DATA_PATH`. If you enable the built-in login flow, also define `APPAUTH_ENABLED=true` and a strong `SINGLEUSER_PASSWORD` before first startup. + +Deployment variables: + +| Variable | Required for production | Default | Purpose | +| --- | --- | --- | --- | +| `WORKTRACKER_DATA_PATH` | Yes | `./.docker-data/couchbase` | Host path mounted to `/data/couchbase` so the embedded Couchbase Lite database survives container replacement. | +| `WORKTRACKER_PORT` | Usually | `8002` | Host port published for the app container. | +| `IMAGE_REGISTRY` | No | `worktracker` | Image repository/name used by the `worktracker` service, for example `ghcr.io/your-org/worktracker`. | +| `IMAGE_TAG` | Usually | `latest` | Image tag to deploy. Pin this to a release tag instead of using `latest`. | +| `ASPNETCORE_ENVIRONMENT` | No | `Production` | ASP.NET Core environment name. Keep this as `Production` for real deployments. | +| `ASPNETCORE_FORWARDEDHEADERS_ENABLED` | Recommended | `true` | Enables forwarded header handling when the app runs behind a reverse proxy or Zero Trust tunnel. | +| `ALLOWED_HOSTS` | Recommended | `*` | ASP.NET Core allowed hostnames. Set this to your public hostname instead of leaving it wide open. | +| `USE_HTTPS_REDIRECTION` | Depends | `false` | Enables ASP.NET Core HTTPS redirection. Leave this `false` when TLS terminates upstream unless you have verified forwarded headers and redirect behavior. | +| `COUCHBASELITE_DATABASE_NAME` | No | `worktracker` | Embedded Couchbase Lite database name. | +| `APPAUTH_ENABLED` | Yes, choose a mode explicitly | `false` | Enables the built-in login flow when `true`. Leave `false` only if access is protected upstream and you want zero-trust style default-admin passthrough. | +| `APPAUTH_DEFAULT_USERNAME` | When `APPAUTH_ENABLED=false` | `Admin` | Display name injected for every request while built-in auth is disabled. | +| `APPAUTH_DEFAULT_USERID` | When `APPAUTH_ENABLED=false` | `ADMIN` | User identifier injected for every request while built-in auth is disabled. | +| `SINGLEUSER_SEED_ON_STARTUP` | No | `true` | Seeds the built-in admin account into Couchbase Lite on first startup if it does not exist yet. | +| `SINGLEUSER_USERNAME` | When `APPAUTH_ENABLED=true` | `Admin` | Username for the seeded built-in account. | +| `SINGLEUSER_PASSWORD` | When `APPAUTH_ENABLED=true` and the database is new | `Disagio` | Initial password for the seeded built-in account. Set this to a strong secret before the first production start. | +| `WORKTRACKER_HEALTHCHECK_INTERVAL` | No | `30s` | Docker healthcheck interval. | +| `WORKTRACKER_HEALTHCHECK_TIMEOUT` | No | `5s` | Docker healthcheck timeout. | +| `WORKTRACKER_HEALTHCHECK_START_PERIOD` | No | `10s` | Grace period before Docker starts evaluating health. | +| `WORKTRACKER_HEALTHCHECK_RETRIES` | No | `3` | Consecutive healthcheck failures before the container is marked unhealthy. | + +Example production `.env`: + +```dotenv +WORKTRACKER_DATA_PATH=/srv/worktracker/couchbase +WORKTRACKER_PORT=8002 +IMAGE_REGISTRY=ghcr.io/your-org/worktracker +IMAGE_TAG=2026.04.20 +ALLOWED_HOSTS=worktracker.example.com +ASPNETCORE_FORWARDEDHEADERS_ENABLED=true +USE_HTTPS_REDIRECTION=false +APPAUTH_ENABLED=true +SINGLEUSER_USERNAME=admin +SINGLEUSER_PASSWORD=replace-with-a-strong-secret +``` + Authentication mode: - Authentication is disabled by default and every request runs as the configured default admin user. This is intended for deployments fronted by Cloudflare Zero Trust. diff --git a/docker-compose.yml b/docker-compose.yml index 08d2020..981a99f 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -5,16 +5,27 @@ services: dockerfile: Dockerfile image: ${IMAGE_REGISTRY:-worktracker}:${IMAGE_TAG:-latest} environment: - ASPNETCORE_ENVIRONMENT: Production - UseHttpsRedirection: "false" + ASPNETCORE_ENVIRONMENT: ${ASPNETCORE_ENVIRONMENT:-Production} + ASPNETCORE_URLS: http://+:8080 + ASPNETCORE_FORWARDEDHEADERS_ENABLED: ${ASPNETCORE_FORWARDEDHEADERS_ENABLED:-true} + AllowedHosts: ${ALLOWED_HOSTS:-*} + UseHttpsRedirection: ${USE_HTTPS_REDIRECTION:-false} + CouchbaseLite__DatabaseName: ${COUCHBASELITE_DATABASE_NAME:-worktracker} CouchbaseLite__Directory: /data/couchbase + AppAuth__Enabled: ${APPAUTH_ENABLED:-false} + AppAuth__DefaultUsername: ${APPAUTH_DEFAULT_USERNAME:-Admin} + AppAuth__DefaultUserId: ${APPAUTH_DEFAULT_USERID:-ADMIN} + SingleUser__SeedOnStartup: ${SINGLEUSER_SEED_ON_STARTUP:-true} + SingleUser__Username: ${SINGLEUSER_USERNAME:-Admin} + SingleUser__Password: ${SINGLEUSER_PASSWORD:-Disagio} ports: - - "8002:8080" + - "${WORKTRACKER_PORT:-8002}:8080" volumes: - ${WORKTRACKER_DATA_PATH:-./.docker-data/couchbase}:/data/couchbase restart: unless-stopped healthcheck: test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8080/healthz >/dev/null 2>&1 || exit 1"] - interval: 30s - timeout: 5s - retries: 3 + interval: ${WORKTRACKER_HEALTHCHECK_INTERVAL:-30s} + timeout: ${WORKTRACKER_HEALTHCHECK_TIMEOUT:-5s} + start_period: ${WORKTRACKER_HEALTHCHECK_START_PERIOD:-10s} + retries: ${WORKTRACKER_HEALTHCHECK_RETRIES:-3}