Deployment and upgrades

Container boundary

The image runs as UID/GID 1000 by default. Compose uses the configured PUID/PGID, a read-only root filesystem, a writable data volume, a temporary filesystem, dropped Linux capabilities, and no-new-privileges. Pre-create the host data directory with matching ownership. The default published endpoint is loopback; explicitly configure the bind address and firewall when another host must reach it.

HTTPS and proxy trust

Set the public HTTPS application origin, preserve the Host header, and configure the proxy to forward the original scheme. Trust forwarded headers only from known proxy addresses. The application does not read arbitrary forwarded-proto headers to decide whether a response needs HSTS. Do not set Uvicorn's trusted proxy list to every address on an exposed server. Keep the internal application port 8888 unless you also adapt the image health check and Compose mapping.

Upgrade to 00.14.01

Patch 00.14.01 adds OAuth authorization-response issuer identification to the experimental native MCP introduced in 00.14.00. There is no new database migration relative to 00.14.00. It stays disabled by default, and existing GPT Actions remain available. A versioned source release does not replace an already running container. Build the release source locally; these instructions do not require a published registry image.

1. Back up the complete SQLite database and settings while writes are stopped, or use a consistent SQLite backup procedure. Preserve the existing private data directory, ownership, environment values, and signing keys.
2. Use a clean source checkout. Fetch tags and select the release shown below. Keep local configuration outside tracked source files, and review any custom Compose changes against the release file.
3. Rebuild and recreate the service from that checkout, where the Dockerfile lives. A restart alone cannot load new source or changed Compose environment variables.
4. Check health, login, tasks, recurrence, calendar, backups, and configured notification providers before enabling the optional integration.
5. To use MCP, set the HTTPS public origin and TIMEBOARDAPP_MCP_ENABLED=true in the supplied Compose .env or your custom service environment. Recreate the container, then follow ChatGPT connection and acceptance testing.

git fetch origin --tags
git switch --detach v00.14.01
docker compose config -q
docker compose up -d --build --force-recreate timeboardapp
docker compose exec timeboardapp python -c 'from app.version import APP_VERSION; print(APP_VERSION)'
curl -fsS http://127.0.0.1:8888/healthz

The version command should report 00.14.01. Adjust the local health-check port if your PORT differs. If you deploy through Portainer or another stack manager, make it rebuild from the new release and redeploy with the updated environment; reusing an old local image does not upgrade the code.

Verify the issuer-identification upgrade

The old v00.14.00 tag remains unchanged. Select v00.14.01 in your checkout or remote Compose build context, rebuild, and recreate. Check that /.well-known/oauth-authorization-server advertises authorization_response_iss_parameter_supported: true, then test a new ChatGPT OAuth connection. A GitHub release and a website deployment do not update your running application.

The historical mcp-issuer-test.1 preview remains available at its original commit and still reports base version 00.14.00. Prefer the numbered patch for ongoing use. Keep the prior image and consistent data backup. A rollback to 00.14.00 removes issuer identification and can prevent new stable-callback connections; it does not undo task edits.

MCP storage and backup

Enabling MCP creates five additive tables for OAuth clients, grants, connections, credentials, and audit/retry history. Existing tables are unchanged. Consistent full SQLite/settings backups preserve connection and retry state; protect these backups as credentials-bearing data. JSON exports omit OAuth state, integration tokens, and MCP audit/retry history. A fresh JSON restore requires reconnecting and does not preserve retry protection.

Disable or roll back

For a quick integration rollback, set TIMEBOARDAPP_MCP_ENABLED=false and recreate the container. If using YAML without an environment override, set mcp.enabled: false and restart. The existing task board, REST API, and GPT Actions remain available. Disabling hides the MCP/OAuth/connection routes but does not revoke stored grants; disconnect first if re-enabling must require fresh consent.

The five MCP tables can remain when rolling source back to 00.13.02, which ignores them. Preserve a matching source/image and full database/settings snapshot and verify login and representative tasks after rollback. Rolling back source does not undo task changes made through MCP. Restore a snapshot only after reconciling newer writes.

Upgrading from older security releases

Deployments predating the authentication hardening must replace old JWTs and browser sessions. Legacy PBKDF2 passwords migrate to Argon2id after successful login. Releases predating Argon2id cannot read migrated passwords, so rollback to those versions requires the matching pre-upgrade database/settings snapshot as well as the image. This older migration warning is separate from the additive 00.13.02 to 00.14.00 MCP upgrade.

Backups and credentials

Generated settings, initial credentials, and JSON backup files are written atomically with mode 0600. Protect the containing directory and external backup destination as well. Do not copy secrets into GPT instructions, public reports, or source-controlled schemas. Test restoration with synthetic or controlled data before relying on a backup.

Operational limits

Use one application process for the built-in SQLite and background scheduler arrangement. Multi-worker/multi-replica operation needs coordinated scheduled jobs and a shared rate limiter. The application limiter is bounded but process-local; add reverse-proxy rate limits and request timeouts. Monitor notification errors rather than assuming configured providers have delivered a message.

CI and release publication

All main-branch pushes run CI. Publication is requested only when the application version increases across the push, or for an explicit manual workflow run. Documentation commits with an unchanged version leave existing tags and release files untouched. The read-only release-intent job prevents an unnecessary write-capable publication job. Versioned release attempts still reject conflicting tags, incomplete releases, and a moved main branch.