everythingbutwork/docs/operations.md

Operations Guide — ToolCTRL everythingbutwork

Lokale Entwicklung

# Postgres (Docker)
docker compose -f docker-compose.dev.yml up -d postgres

# Migration anwenden
cp .env.example .env
pnpm --filter @cockpit/db migrate:up

# API und Web
pnpm --filter api dev    # :3000
pnpm --filter web dev    # :5173 (proxy /api+/trpc → :3000)

Authentik-Setup (Story 1.3)

1. In Authentik (auth.tool-ctrl.de) als Admin einloggen.
2. Providers → Create → OAuth2/OpenID Provider
   • Name: cockpit
   • Authorization flow: default-provider-authorization-explicit-consent
   • Client type: Confidential
   • Client ID + Secret automatisch generieren lassen, in .env übertragen.
   • Signing key: authentik Self-signed Certificate
   • Redirect URIs: https://cockpit.tool-ctrl.de/api/auth/callback (Prod), http://localhost:3000/api/auth/callback (Dev)
3. Applications → Create
   • Name: everythingbutwork
   • Slug: cockpit
   • Provider: cockpit
   • Launch URL: https://cockpit.tool-ctrl.de/
4. .env-Variablen ausfüllen:

   AUTHENTIK_ISSUER=https://auth.tool-ctrl.de/application/o/cockpit/
   AUTHENTIK_CLIENT_ID=<aus Authentik>
   AUTHENTIK_CLIENT_SECRET=<aus Authentik>
   

5. Gruppen-Mapping (OQ-1) wird im API-Code per AUTHENTIK_GROUP_TO_AREA-Variable umgesetzt (Erweiterung in späterer Story).

Production-Deployment

# Auf der ToolCTRL-Infra:
git pull
docker compose pull
docker compose build
docker compose up -d

# Migration:
docker compose exec api node -e "import('@cockpit/db/client').then(async ({ createDbClient }) => { /* migrate via drizzle-kit in CI */ })"
# Alternativ direkt via drizzle-kit von außen mit Production-DATABASE_URL.

Backups (Story 6.3)

Tägliches pg_dump via Cron-Endpoint POST /internal/cron/pg-dump-backup mit Bearer-Token. 14 Tage Retention. Restore-Drill quartalsweise.

Restore-Anleitung

1. API stoppen: docker compose stop api
2. Backup aus /backups auswählen.
3. Restore in temporäre DB: docker compose exec postgres pg_restore -U cockpit -d cockpit_restore /backups/<file>.sql.gz
4. Smoke-Test: curl http://localhost:3000/api/health
5. API wieder starten: docker compose start api

Healthcheck

GET /api/health liefert:

{ "status": "ok|degraded", "db": "ok|down", "authentik": "ok|down", "timestamp": "..." }

Wird von Docker und (Phase 2) externer Uptime-Überwachung genutzt.

OQ-5 (Archivierung)

Soft-Delete via project.archiviert=true + archiviert_am. Kein automatisches Löschen. Manuelle Bereinigung bei Bedarf durch DB-Admin via Migration.