Configuration

Configuration sources

TIMEBOARDAPP_SETTINGS selects the YAML file, defaulting to /data/settings.yml. The legacy TIMEBOARD_* environment prefix is accepted as a compatibility fallback. First-run signing keys are random, durable, and distinct. Writable log and backup paths follow the configured SQLite database directory, not a hard-coded image path.

app:
  name: TimeboardApp
  timezone: America/Denver
  host: 0.0.0.0
  port: 8888
  base_url: https://tasks.example.com
security:
  # Generated automatically; preserve these across restarts.
  session_secret: <generated-session-secret>
  jwt_secret: <different-generated-jwt-secret>
  secure_cookies: null
  outbound_allowed_hosts: []
database:
  path: /data/timeboardapp.db

TIMEBOARDAPP_BASE_URL overrides the public application origin. It must not point to this static documentation website. HTTPS enables Secure cookies automatically when secure_cookies is null. Explicit identical signing-key overrides are rejected. Weak legacy placeholders are repaired in the writable settings file; failure to persist repaired keys stops startup rather than silently rotating keys on every restart.

Compose environment

CONFIG_DATA selects the host data directory; PUID and PGID select the actual process user through Compose's user setting. PORT selects the host-published port. BIND_ADDRESS defaults to loopback. CONTAINER_NAME renames the container, not the stable timeboardapp service. No pre-created external networks are required. The application timezone is configured in app.timezone; the container's TZ alone does not change that setting.

Native MCP and OAuth

MCP is included in 00.14.01 and disabled by default. Set TIMEBOARDAPP_MCP_ENABLED=true and TIMEBOARDAPP_BASE_URL=https://tasks.example.com in the supplied Compose .env, or set the values directly in your service environment. This release passes the flag into the container. A blank flag preserves the YAML setting; a non-empty environment value overrides it. Recreate the container after changing Compose environment values.

mcp:
  enabled: false
  allowed_redirect_uris:
    - https://chatgpt.com/connector_platform_oauth_redirect
  access_token_seconds: 900
  refresh_token_days: 30
  max_clients: 200

To use YAML instead, set mcp.enabled: true in the persistent settings and restart with no non-empty environment override. MCP requires an HTTPS origin with no path prefix and cannot run in public demo mode. Proxy the complete application, including OAuth and discovery paths; do not proxy only /mcp.

Version 00.14.01 advertises RFC 9207 issuer identification and includes the exact published issuer in authorization callbacks. Its default stable callback supports eligible new ChatGPT connections; existing connections may use callback-specific URLs. Copy the exact callback shown by your ChatGPT setup into mcp.allowed_redirect_uris if it differs from the default. Wildcards are rejected. TIMEBOARDAPP_MCP_REDIRECT_URIS can override the list with comma-separated exact URLs when passed into the container; add that variable explicitly to a custom Compose service. Changing the issuer or callbacks can require reconnecting. Local Inspector tests may use exact HTTP loopback callbacks.

Access tokens default to 15 minutes (allowed 60–3600 seconds). Refresh tokens rotate within a 30-day absolute connection lifetime (allowed 1–90 days). Dynamic client registration is capped at 200 clients by default (allowed 1–10000). OAuth state and retry tombstones occupy the database; plan storage before broad use. Follow ChatGPT setup and the isolated testing guide.

Email and notification settings

Email, logging, Windows notification credentials, and automatic backup settings are administered in the database-backed UI. Legacy YAML email/logging settings seed initial values. SMTP with STARTTLS and SendGrid are supported; real delivery requires provider credentials and network access. Password-reset links additionally require a configured public base URL.

Outbound destination policy

Public notification URLs require HTTPS. Redirects are not followed, response bodies are bounded, and DNS results are validated before a numeric destination is connected. Loopback, link-local/metadata, multicast, reserved, and IPv6 transition destinations are blocked. An operator may list exact trusted LAN hostnames in security.outbound_allowed_hosts for a private Gotify/ntfy service. Wildcards are not supported; the exception does not allow loopback or metadata addresses. Configure outbound firewall restrictions as an additional layer.

Retention

Per-user archive retention and administrator-configured logs/backups affect permanent deletion. Review the retention settings before importing data or enabling scheduled purges.