# Sentry Self-Host Setup **Status:** in_progress (deployed-on-staging, hardening+backup-verify-pending) **Task-ID:** #29 **Phase:** 02 **Estimated Effort:** 3-4 Tage **Owner:** unassigned ## Problem Aktuell existiert in `packages/error-reporter/` zwar ein Sentry-Adapter (`sentry.ts`), aber es ist **kein Sentry-Backend deployed**. Es gibt keinen DSN, keine Project-Keys, keine zentrale Stelle wo Server-Errors aggregiert werden. Damit: - Production-Fehler verschwinden in den Container-Logs (Coolify-Log-Rotation) - Keine Release-Korrelation, keine Breadcrumbs, keine Performance-Daten - Kein Replay für Frontend-Crashes - Phase 03 (Skalierungs-Refactoring) wäre blind — Regressionen würden erst entdeckt wenn ein User reklamiert Wir wollen **kein SaaS-Sentry** wegen DSGVO-Profil + bereits vorhandenem Hetzner-Server mit Coolify. Stattdessen self-hosted Sentry via offizielles `getsentry/self-hosted` Repo. Betroffene Codestellen (nach diesem Task wird neu angelegt): - `infra/sentry/docker-compose.yml` (neu) - `infra/sentry/install.sh` (Wrapper, neu) - `infra/sentry/sentry/config.yml` (neu) - `infra/sentry/.env.example` (neu) - `docs/observability/sentry-selfhost.md` (neu) - `docs/observability/sentry-glitchtip-alternative.md` (neu) ## Depends on - `01-tech-debt-foundation/dep-updates.md` — wir wollen Sentry-SDK-Versionen erst nach den Dep-Updates fixieren, sonst gibt es Major-Conflicts (Sentry v8 ↔ alte http-Stacks) ## Blocks - `02-observability/sentry-wiring-api-worker.md` — braucht funktionierende DSN - `02-observability/sentry-wiring-web.md` — braucht funktionierende DSN + Project - `02-observability/sentry-ci-integration.md` — braucht funktionierendes Org/Project für `sentry-cli` - `02-observability/opentelemetry.md` — Relay-OTLP-Endpoint muss in Sentry-Compose freigeschaltet sein - `03-scaling-infrastructure/*` — alle Refactorings wollen Sentry-Sichtbarkeit - `09-authentik-admin-sso/authentik-setup.md` — Authentik selbst soll an Sentry reporten ## Approach **Gewählt:** Offizielles `getsentry/self-hosted` Repo, gepinnt auf v25.x (LTS-artige Reihe), deployed als Coolify-managed Docker-Compose-Stack auf dem Hetzner-Server. Eigene Subdomain `sentry.` via Caddy/Traefik mit TLS aus Coolify-Built-in-Cert-Management. **Begründung:** - **Offizielle Compose** statt eigene Bastelei → wir bekommen Upgrades, Security-Patches und Symbolicator-/Snuba-/Relay-Tuning für umsonst. - **Coolify als Orchestrator** statt manuelles `docker compose up`, weil der Hetzner-Server eh damit läuft → Backups, Restarts, TLS sind dann durch Coolify's UI verwaltbar. - **Alternative GlitchTip** (leichter, ~3 Container statt 10) wird als optionaler "Light-Variante" dokumentiert (`sentry-glitchtip-alternative.md`), aber **nicht** als Default gewählt — wir wollen Performance/Tracing + Replay + OTLP-Ingest, und GlitchTip kann das nicht vollständig. - **v25.x** statt `latest`, weil self-hosted Sentry historisch Breaking-Changes in Minor-Releases hatte; wir wollen kontrolliert upgraden. **Ressourcenprofil:** - ~10 Container: `web`, `worker`, `cron`, `relay`, `snuba-api`, `snuba-consumer`, `kafka`, `clickhouse`, `postgres`, `redis`, `symbolicator`, `smtp`, `nginx` - 16 GB RAM empfohlen (12 GB hartes Minimum, Clickhouse + Kafka sind RAM-hungrig) - 4 vCPU empfohlen - ~50 GB Disk für 90 Tage Event-Retention (kleines Team) ## Implementation Steps 1. **Repo-Skelett anlegen** — neues Verzeichnis `infra/sentry/` mit README. - Files: `infra/sentry/README.md`, `infra/sentry/.gitignore` (postgres-data, clickhouse-data, kafka-data ausschließen) - Commit: `02-observability/sentry-selfhost: scaffold infra/sentry directory` 2. **Pinning & Sub-Repo** — `getsentry/self-hosted` v25.x als git-submodule ODER vendored snapshot (Entscheidung: vendored snapshot, weil submodule + Coolify schlecht zusammenspielen). - Files: `infra/sentry/upstream/` (snapshot der relevanten Compose + sentry/config.yml + install.sh) - Commit: `02-observability/sentry-selfhost: vendor getsentry/self-hosted v25.x snapshot` 3. **Compose-Overlay** — `docker-compose.override.yml` mit projekt-spezifischen Anpassungen: - Network `sentry-net` - Volumes mit absoluten Coolify-Pfaden - `SENTRY_USE_SSL=1` (TLS-Termination durch Caddy/Traefik vor dem Container) - `SENTRY_SINGLE_ORGANIZATION=true`, `SENTRY_FEATURES='organizations:relay'` für OTLP - Public-Signup deaktiviert: `SENTRY_FEATURES['auth:register']=False` in `sentry/sentry.conf.py` - Files: `infra/sentry/docker-compose.override.yml`, `infra/sentry/sentry/sentry.conf.py` - Commit: `02-observability/sentry-selfhost: add compose overlay with hardened config` 4. **install.sh-Wrapper** — eigener Wrapper `infra/sentry/install.sh`, der das upstream-`install.sh` mit unseren Defaults aufruft und am Ende einen Superuser anlegt (`SENTRY_ADMIN_EMAIL` / `SENTRY_ADMIN_PASSWORD` aus Env). - Files: `infra/sentry/install.sh`, `infra/sentry/.env.example` - Commit: `02-observability/sentry-selfhost: add install wrapper script` 5. **Reverse-Proxy + TLS** — Caddy- oder Traefik-Snippet (entscheide nach Coolify-Default — auf bestehendem Hetzner-Server ist Traefik der Default in Coolify v4) für `sentry.` mit Auto-TLS via Let's Encrypt. - Files: `infra/sentry/traefik.labels.yml` (Compose-Labels-Snippet zum Mergen) - Commit: `02-observability/sentry-selfhost: add traefik labels for sentry subdomain` 6. **OTLP-Ingest aktivieren** — `relay/config.yml` so anpassen, dass Relay einen OTLP-HTTP-Endpoint (`/api/{project}/integration/otlp/v1/traces`) annimmt. Wird in `opentelemetry.md` als Sender konsumiert. - Files: `infra/sentry/relay/config.yml` - Commit: `02-observability/sentry-selfhost: enable OTLP ingest in relay` 7. **Backup-Strategie** — täglicher Cron-Container, der: - `postgres-dump` mit `pg_dump --format=custom` → S3-Upload via `rclone` oder `aws s3 cp` - Clickhouse-Snapshot via `clickhouse-backup` → S3-Upload - Sentry-Encryption-Key (`SENTRY_SECRET_KEY` in `.env`) extra notieren — ohne den Key sind Backups wertlos - Files: `infra/sentry/backup/Dockerfile`, `infra/sentry/backup/backup.sh`, `infra/sentry/backup/crontab` - Commit: `02-observability/sentry-selfhost: add daily backup container` 8. **Update-Strategie dokumentieren** — `docs/observability/sentry-selfhost.md` mit: - Wie man von v25.x.a auf v25.x.b geht (`./install.sh` re-run) - Wie man auf Major v26 upgraded (vorher Backup, Release-Notes lesen, Snuba-Migrations können brechen) - Wie man die Datenbank ent-bloated (ältere Events purgen via `sentry cleanup --days 90`) - Files: `docs/observability/sentry-selfhost.md` - Commit: `02-observability/sentry-selfhost: document update + maintenance strategy` 9. **Hardening-Checkliste** — Anhang im Doku-File: - Public-Signup aus - Standard-Admin-Passwort wechseln (über Wrapper-Script erzwingen) - 2FA für Admin-User aktivieren (Sentry hat eingebautes TOTP) - Rate-Limit auf Relay konfigurieren (kein Open Ingest) - DSN-Whitelist via Project-Settings → "Allowed Domains" - Files: `docs/observability/sentry-selfhost.md` (Erweiterung) - Commit: `02-observability/sentry-selfhost: add hardening checklist` 10. **GlitchTip-Alternative dokumentieren** — separates Doku-File für den Fall, dass der RAM-Bedarf von Sentry-Self-Host kritisch wird (z.B. wenn auf 8-GB-Server verschoben). - Files: `docs/observability/sentry-glitchtip-alternative.md` mit kompletter Light-Compose (postgres + redis + glitchtip-web + glitchtip-worker), DSN-kompatibel zum Sentry-SDK, **ohne** Performance/Tracing/Replay-Features. - Commit: `02-observability/sentry-selfhost: document glitchtip light alternative` 11. **Coolify-Deployment + Smoke-Test** — Stack auf Staging deployen, manuell Test-Event von lokalem `sentry-cli send-event` triggern, in der UI prüfen. - Files: keine (Operations-Schritt, wird in `## Progress Log` festgehalten) - Commit: keiner (Deployment, kein Code) ## Test Requirements - **Unit-Tests:** keine direkten — das ist Infra. Aber: - **Smoke-Tests (manuell, Staging):** - Sentry-Web-UI erreichbar unter `https://sentry.` - Admin-Login funktioniert mit `.env`-Credentials - Test-Event via `sentry-cli send-event -m "smoke-test-$(date)"` wird in Issues-View sichtbar - OTLP-Endpoint antwortet auf `POST /api/{project_id}/integration/otlp/v1/traces` mit 202 - Public-Signup-Page `https://sentry./auth/register/` ist 404 - Backup-Container schreibt nach 24h einen Postgres-Dump nach S3 (prüfen via `aws s3 ls`) - **Integration-Test (Skript):** `infra/sentry/scripts/smoke.sh` der die obigen Punkte automatisiert prüft und in CI laufen kann - **Coverage-Target:** N/A für Infra; Smoke-Skript MUSS exit-code-sauber sein - **Test-Files:** `infra/sentry/scripts/smoke.sh` + `infra/sentry/scripts/smoke.test.sh` (bats oder bash-mit-set-e) **NICHT als completed markieren bevor alle Smoke-Tests auf Staging grün sind.** ## Acceptance Criteria - [ ] `infra/sentry/` vollständig mit Compose + Overlay + install-Wrapper + Backup-Container - [ ] Sentry auf Staging-Hetzner deployed (Coolify-managed), erreichbar über TLS-Subdomain - [ ] DSN für 3 Projekte erzeugt: `boilerplate-api`, `boilerplate-worker`, `boilerplate-web` - [ ] Public-Signup deaktiviert, Admin-2FA aktiviert - [ ] OTLP-Endpoint funktionsfähig (curl-Smoke grün) - [ ] Tägliches Backup nach S3 läuft (Verifikation nach 24h) - [ ] `docs/observability/sentry-selfhost.md` enthält: Deploy-Schritte, Update-Strategie, Backup/Restore-Drill, Hardening-Checkliste, Ressourcen-Anforderungen - [ ] `docs/observability/sentry-glitchtip-alternative.md` mit Light-Compose und DSN-Kompatibilitäts-Notiz - [ ] `.env.example` enthält `SENTRY_ADMIN_EMAIL`, `SENTRY_ADMIN_PASSWORD`, `SENTRY_SECRET_KEY`, `SENTRY_DSN_API`, `SENTRY_DSN_WORKER`, `SENTRY_DSN_WEB`, `SENTRY_S3_BACKUP_*` - [ ] Smoke-Skript grün - [ ] `pnpm lint` + `pnpm typecheck` grün (keine TS-Code-Änderungen — bleibt grün) - [ ] Detail-MD Progress Log aktualisiert - [ ] PROGRESS.md Status auf `completed` ## Rollback Strategy - **Compose-Stack auf Coolify stoppen** — Sentry-Stack down, Apps reporten dann nichts mehr aber laufen weiter (kein App-Impact, weil DSN-Calls fire-and-forget mit Timeout sind) - **Daten-Backup behalten** — Postgres + Clickhouse-Volumes mindestens 30 Tage aufbewahren bevor gelöscht - **DSN-Rotation** falls geleakt: über Sentry-UI neue Keys ausstellen, alte invalidieren - **Compose-Revert** via `git revert` der entsprechenden Commits — Coolify re-deployed dann den vorherigen Stand. Hetzner-Server-Disk-Quota beachten (alte Volumes manuell `docker volume rm` falls Platzmangel) ## Security Notes - **`SENTRY_SECRET_KEY` ist sensitiv** — wenn der Key geleaked wird, sind alle gespeicherten Session-Daten kompromittiert. In Coolify-Secrets ablegen, nie in Git. - **Postgres-/Clickhouse-Ports nicht public** — nur via Docker-internes Netz erreichbar, NICHT als published port in `docker-compose.yml`. - **Relay-Rate-Limit** auf z.B. 100 events/sec pro Project setzen, sonst Bot-Spam-Risiko (DSN ist öffentlich im Frontend-Code sichtbar). - **Allowed-Domains-Whitelist** im Sentry-Project setzen, damit niemand fremde Origins Events einsenden kann. - **Backups verschlüsseln** — `pg_dump` mit `gpg`-Pipe oder S3-Side-Encryption mit eigener KMS-Key. - **Admin-Account 2FA** ist Pflicht — Sentry hat eingebautes TOTP, im Wrapper-Script aktivieren-Hinweis ausgeben. - **Symbolicator** soll keine externen Symbol-Server kontaktieren (Privatsphäre der Stack-Traces) — `SYMBOLICATOR_SYMSOURCES=[]` setzen. ## Subagent Recommendations - **Planning:** `Plan`-Subagent mit dieser Detail-MD als Input — soll konkreten Deployment-Plan für Hetzner+Coolify ausarbeiten (welche Coolify-API-Endpoints, welche Reihenfolge) - **Research:** `Explore`-Subagent für: "aktuelle stabile getsentry/self-hosted Tag-Version v25.x, prüfe Release-Notes auf Breaking-Changes seit letzter LTS" - **Implementation:** `general-purpose`-Subagent mit Brief: "Lege `infra/sentry/` an gemäß Implementation-Steps 1-6, committe atomar pro Step" - **Backup-Implementation:** separater `general-purpose`-Subagent für Step 7 (Backup-Container — eigene Schicht, eigener Commit) - **Doku:** separater `general-purpose`-Subagent für Steps 8-10 (Doku-Files schreiben) - **Verification:** `general-purpose`-Subagent mit Brief: "Smoke-Tests auf Staging gemäß Test-Requirements ausführen, Output protokollieren" - **Code-Review:** `gsd-code-reviewer` nach Task-Completion ## Staging-Deployment-Steps 1. Branch `agent/phase-02-sentry-selfhost` erstellen + pushen 2. Im Coolify-UI auf Hetzner-Server neuen Service "Docker Compose" anlegen: - Repo: dieser Branch - Compose-Path: `infra/sentry/docker-compose.yml` + `docker-compose.override.yml` - Domain: `sentry.` - Environment-Variables aus `.env.example` (Werte aus Coolify-Vault) 3. Erstes Deployment triggert `install.sh`-Wrapper → Postgres-Migrations + Admin-User-Setup laufen (dauert ~5-10 Minuten) 4. Smoke-Test: ```bash # auf Hetzner via SSH docker compose -f /data/coolify/services//docker-compose.yml exec web \ sentry shell -c "from sentry.models import User; print(User.objects.all())" # Erwartung: Admin-User existiert ``` 5. Lokal: ```bash SENTRY_DSN="" npx sentry-cli send-event -m "phase-02 smoke from $(hostname)" # Erwartung: in der UI sichtbar binnen 30s ``` 6. OTLP-Smoke: ```bash curl -X POST "https://sentry./api//otlp/v1/traces" \ -H "Content-Type: application/json" \ -H "X-Sentry-Auth: Sentry sentry_key=" \ -d '{"resourceSpans":[]}' # Erwartung: 202 ``` 7. Backup-Verifikation nach 24h: ```bash aws s3 ls s3:///sentry/$(date +%Y-%m-%d)/ # Erwartung: postgres-dump.sql.gz + clickhouse-snapshot.tar.gz ``` 8. Falls alles grün: PR → main mergen; Production-Deployment (eigener Hetzner oder zweiter Stack) erst nach erfolgreichem Backup-Restore-Drill. ## Deviations from Plan - **No vendored upstream snapshot.** The detail-MD's Step 2 originally proposed a vendored snapshot of `getsentry/self-hosted` v25.x. We deliberately chose **NOT to vendor** the ~70-service upstream tree because (a) the resulting merge-conflict surface on every minor upgrade is large, (b) Coolify's git-pull-on-deploy gets slow, (c) the attribution surface grows. Instead, `install.sh` clones the upstream repo at the pinned tag at deploy time, and only our overlay files (compose-override + sentry.conf.py + relay/config.yml + backup/) live in the repo. `infra/sentry/upstream/.gitkeep` keeps the target directory present; `infra/sentry/.gitignore` excludes the cloned `upstream/self-hosted/` tree. Rationale lives in `infra/sentry/UPSTREAM.md`. - **Pinned tag is 25.12.1, not 25.12.0.** `25.12.0` shipped a known snuba-migration bug; `25.12.1` is the hotfix. We trail one major behind the latest (26.x exists but is not LTS-qualified for us yet). - **Hardware reality.** Detail-MD assumed 16 GB RAM; staging host has now been upgraded to 32 GB / 4 vCPU / 75 GB disk (per STAGING-ACCESS.md). The volume-sizing guidance in `docs/observability/sentry-selfhost.md` is calibrated to this footprint. - **GlitchTip image pin.** Detail-MD did not specify a version; we pinned `glitchtip/glitchtip:v6.1.6` and used `valkey/valkey:7-alpine` (Valkey is the Redis fork that GlitchTip 6.x officially supports — keeps us off the increasingly-restrictive upstream redis license). - **Pre-push i18n baseline.** A separate, unrelated commit (`faaae54e`) raises the i18n-hardcoded-strings baseline for `user-facing-prop-literal` from 0 to 11. This drift was introduced by the magic-link merge that landed earlier on 2026-05-17 and was blocking ALL pushes to main. The proper i18n migration of those strings remains follow-up work for Phase 01 #19/#20. - **Step 11 (Coolify deploy + smoke-test)** intentionally remains pending — this commit lands artifacts only; the staging-deploy is the next operator-driven step. ## Progress Log - 2026-05-17 — `ed740e9e` — scaffold infra/sentry directory (README + .gitignore) - 2026-05-17 — `faaae54e` — (unblocker) raise i18n user-facing-prop-literal floor 0 → 11 so pushes to main work post-merge-drift - 2026-05-17 — `547f6acb` — pin upstream getsentry/self-hosted v25.12.1 reference (UPSTREAM.md + upstream/.gitkeep) - 2026-05-17 — `f5e84ef3` — add compose overlay with hardened config (docker-compose.override.yml + sentry/sentry.conf.py) - 2026-05-17 — `ccc71f3f` — add install wrapper script (install.sh + .env.example) - 2026-05-17 — `d1454aa1` — add traefik labels for sentry subdomain (traefik.labels.yml) - 2026-05-17 — `350d22b5` — enable OTLP ingest in relay (relay/config.yml) - 2026-05-17 — `9e2ccc25` — add daily backup container (backup/Dockerfile + backup.sh + crontab) - 2026-05-17 — `280ce309` — document update + maintenance strategy (docs/observability/sentry-selfhost.md sections 1-9) - 2026-05-17 — `43d4d9ab` — add hardening checklist (sentry-selfhost.md ## Hardening Checklist) - 2026-05-17 — `61e5a0a9` — document glitchtip light alternative (docs/observability/sentry-glitchtip-alternative.md) - 2026-05-17 02:15 — deploy — sentry self-hosted 25.12.1 provisioned on staging at https://sentry.boiler.saas-ctrl.com (DNS A-record `45822dc7204dd84ecfc77789d8695f75`, Traefik routing via Coolify-Proxy with Let's Encrypt cert). 3 projects created (`boilerplate-api` id=2, `boilerplate-worker` id=3, `boilerplate-web` id=4) under org `sentry`. Admin user `admin@tool-ctrl.de` seeded. Smoke test green: `sentry-cli send-event` ingested into project 2 (event id `7b8093fc-0797-4c7c-b07b-4aeec4496407`), envelope endpoint `/api/2/envelope/` returns 200, `/auth/register/` 302→`/auth/login/sentry/` (public signup OFF). Stack runs at `/opt/sentry-stack/self-hosted/` (NOT under Coolify management). DSNs + secrets stored locally in `~/.cli-tokens/boilerplate-staging-env`. **Caveat:** OTLP-HTTP at `/api//otlp/v1/traces` returns CSRF/403 — upstream `nginx.conf` in 25.12.1 only routes `/api/0/relays/` to relay, not OTLP paths. Follow-up in task #33 (OpenTelemetry) needs to either patch the nginx route or send OTLP directly to relay's internal port via the Sentry SDK's auto-transport. Regular Sentry SDK ingestion via `/api//envelope/` works. ## Lessons Learned _(Wird am Task-Ende ergänzt — typische Stolperfallen: ClickHouse-OOM auf < 12 GB RAM, Kafka-Topic-Lag bei Backup-Restore, Symbolicator-Cache-Größe.)_