Operate Tracker
Tracker is the delivery authority for versions, roadmap tasks, and bugs. Its SQLite database is the source of truth. GitHub Issues is only the external bug surface.
The pinned Tracker README still describes an Auth hub, but the production Compose definition routes Tracker through Caddy forward-auth to Authentik. Use the production authentication contract for sign-in recovery.
Service contract
Section titled “Service contract”| Field | Verified value |
|---|---|
| Purpose | Versioned roadmap, kanban, delivery status, and public bug synchronization. |
| Audience | Platform users read status. Maintainers manage delivery records. Operators preserve the database. |
| Public boundary | https://tracker.beskid-lang.org. |
| Local boundary | The service listens on http://localhost:3000 in the reference container. |
| Authentication | Tracker signs users in through Authentik behind the shared Caddy edge. |
| Persistent state | SQLite persists below TRACKER_DATA_DIR in the tracker-data volume. |
| Container image | ghcr.io/cyber-nomad-collective/beskid-tracker. |
| Health check | The container runs an internal GET /api/health on port 3000; the public route requires Authentik. |
| Deployment owner | Root platform delivery publishes the image. The Tracker service owns delivery data. |
| Secret source | OpenBao path secret/beskid/<lane>/tracker. |
| Monitoring | Health status, webhook results, and reconciliation output cover runtime and synchronization. |
| Recovery | Restore the SQLite volume before replaying external bug events. Never replace roadmap state with GitHub data. |
Prerequisites
Section titled “Prerequisites”Confirm the selected delivery version and the configured TRACKER_DATA_DIR. Treat Tracker as the delivery authority. Obtain a consistent SQLite backup before data maintenance.
Actions
Section titled “Actions”- Inspect the Tracker container health state against the service contract’s internal
GET /api/healthon port3000. - Record the internal healthcheck status.
- Verify that the configured volume contains the active SQLite database.
- Run the read-only reconciliation plan before an import or bug synchronization change.
Expected result
Section titled “Expected result”The internal /api/health check succeeds. An anonymous request to the public route receives the Authentik sign-in redirect, which is not backend health evidence. SQLite remains the delivery authority, and GitHub synchronization affects only eligible bugs.
Recovery
Section titled “Recovery”If the internal healthcheck fails, inspect the volume mount and session configuration. If reconciliation differs from the expected plan, stop the mutation. Then restore the SQLite backup, redeploy the prior image, and replay only verified bug events.
Next task
Section titled “Next task”For signed-in delivery reading, see Read Tracker. For authorized delivery changes, change the Standard without changing delivery ownership.