Running and debugging with Docker or local Couchbase Lite storage

Quick run (Docker Engine required):

1. Build and start services with the development override:

   docker compose up --build

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 runtime-only and expects the image referenced by IMAGE_REGISTRY and IMAGE_TAG to already exist.
• 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.

Production start:

• Copy docker-compose.yml and the matching env file to the server.
• Pull the published image first, then start the stack with docker compose --env-file production.env up -d.

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:

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.
• Re-enable the built-in login flow by setting AppAuth__Enabled=true or changing AppAuth:Enabled to true in appsettings.json.
• The default admin identity used while auth is disabled is configured under AppAuth:DefaultUsername and AppAuth:DefaultUserId.

Health endpoint:

• GET /healthz returns JSON health information, including whether built-in authentication is enabled and whether the Couchbase Lite collections initialized correctly.

Docker persistence:

• The app now uses an embedded Couchbase Lite database stored under /data/couchbase inside the container.
• The compose file mounts that path from ${WORKTRACKER_DATA_PATH:-./.docker-data/couchbase} on the host.
• Set WORKTRACKER_DATA_PATH before docker compose up if you want to move the database elsewhere.

Development in VS Code without Docker:

• Use the WorkTracker: Debug Local launch configuration.
• VS Code builds the project, starts the app directly with ASPNETCORE_ENVIRONMENT=Development, and opens the local URL when the server is ready.
• Local development data is stored in App_Data/couchbase-dev by default.

Development in Docker:

• The override file keeps a containerized dotnet watch flow for cases where you still want Docker.
• The development container mounts the workspace into /workspace and stores its Couchbase Lite files under ./.docker-data/couchbase-dev on the host.

Debugging in Docker from VS Code:

• Use the WorkTracker: Debug in Docker launch configuration.
• VS Code brings up the development container with docker compose, builds the app in Debug, and launches WorkTracker.dll under vsdbg inside the container.
• VS Code waits for the app to report that it is listening before opening Microsoft Edge in browser debug mode against http://localhost:8002.
• The app remains available at http://localhost:8002 while the debugger is attached.
• Stopping the debug session runs docker compose down for the debug stack.

Manual development start:

• docker compose up --build

Manual shutdown:

• docker compose down

Docker Playwright smoke tests:

• Run docker compose -f docker-compose.yml -f docker-compose.tests.yml up --build --abort-on-container-exit --exit-code-from playwright playwright
• The suite starts the app in Docker, waits for /healthz, and verifies that protected pages load without a login screen.

Notes:

• The base compose file remains production-oriented; the override file is the optional containerized development layer.
• docker compose up --build still works locally because Docker Compose auto-loads docker-compose.override.yml, which carries the build settings.
• The first container build takes longer because the dev image installs the .NET debugger.
• The Dockerfile uses the .NET 10 *-noble images so local builds and container builds stay aligned with the SDK available in VS Code.