115 lines
7.2 KiB
Markdown
115 lines
7.2 KiB
Markdown
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`:
|
|
|
|
```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.
|
|
- 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.
|