HiveGrid-Wireframes/hivegrid-cloud/infra/sentry

infra/sentry — Self-Hosted Sentry Stack

This directory contains the artifacts to deploy a self-hosted Sentry instance on the staging Hetzner host (boilerplate-staging, see docs/improvement-plan/archive/STAGING-ACCESS.md) via the existing Coolify-managed Docker-Compose runtime.

Purpose

• Aggregate server-side errors from the API + Worker containers
• Aggregate browser errors (incl. Replay + Performance) from the Web app
• Ingest OpenTelemetry traces via the Relay OTLP-HTTP endpoint (consumed in Phase 02 task #33)
• Provide a DSGVO-compliant, EU-hosted alternative to SaaS Sentry

The companion light-weight alternative (GlitchTip) is documented in docs/observability/sentry-glitchtip-alternative.md and is not the default — it lacks full Performance / Replay / OTLP support.

Prerequisites

• Hetzner host with ≥ 16 GB RAM, ≥ 4 vCPU, ≥ 50 GB free disk (Clickhouse + Kafka + Symbolicator are RAM-hungry; the staging host now has 32 GB RAM after the recent upgrade)
• Docker Engine ≥ 24 + Docker Compose v2 (provided by Coolify)
• Traefik v3.6 reverse-proxy from coolify-proxy (Let's Encrypt ACME via letsencrypt cert resolver)
• DNS-record sentry.boiler.saas-ctrl.com → 46.225.5.93

Layout

infra/sentry/
├── README.md                       # this file
├── .gitignore                      # excludes runtime volumes + secrets
├── UPSTREAM.md                     # pinned getsentry/self-hosted version + clone strategy
├── upstream/                       # populated at deploy time by install.sh (NOT committed)
│   └── .gitkeep
├── docker-compose.override.yml     # overlay merged on top of upstream compose
├── sentry/sentry.conf.py           # python-config overlay (single-org, no-signup, OTLP)
├── relay/config.yml                # Relay OTLP-ingest config
├── traefik.labels.yml              # Compose-fragment with Traefik labels
├── install.sh                      # wrapper that clones upstream + applies overlays + installs
├── .env.example                    # template for SENTRY_* secrets
└── backup/                         # daily backup container
    ├── Dockerfile
    ├── backup.sh
    └── crontab

Deploy

See docs/observability/sentry-selfhost.md (full deploy + upgrade + backup runbook). High-level:

1. Copy .env.example → .env, fill secrets (Coolify-Vault).
2. Run ./install.sh (clones upstream at pinned tag, applies overlays, installs).
3. In Coolify, attach this stack to the sentry.boiler.saas-ctrl.com domain.
4. Smoke-test per ## Test Requirements in docs/improvement-plan/02-observability/sentry-selfhost-setup.md.

Versioning

• Upstream pin: getsentry/self-hosted tag 25.12.1 (see UPSTREAM.md for rationale — skipping the buggy 25.12.0 migration release; staying on the v25.x LTS-ish line until we manually qualify v26.x).
• GlitchTip alternative pin: glitchtip/glitchtip:v6.1.6.