HiveGrid-Wireframes/hivegrid-cloud/infra/sentry/UPSTREAM.md

Upstream Pin: getsentry/self-hosted

Pinned Version

Field	Value
Upstream repo	https://github.com/getsentry/self-hosted
Pinned git tag	25.12.1
Release line	v25.x (LTS-ish; we treat the v25.x line as our long-term track until v26.x is qualified)
Why not 25.12.0	25.12.0 shipped a known migration bug in the snuba-api migration step that aborts the installer mid-way; 25.12.1 is the hotfix.
Why not 26.x	v26.x is the current major and introduces breaking schema changes (Snuba consumers + ClickHouse-table renames). We intentionally trail one major behind to land changes after they have been hot-fixed in the wild.
Image-tag mapping	All Sentry component images (sentry, snuba, relay, symbolicator, etc.) pull the 25.12.1 tags as defined in the upstream Compose.
Companion GlitchTip pin	glitchtip/glitchtip:v6.1.6 (see docs/observability/sentry-glitchtip-alternative.md) — used only when the full Sentry stack is too heavy.

Why we do NOT vendor the upstream snapshot

The upstream getsentry/self-hosted repository at 25.12.1 contains ~70 services in its base Compose plus a non-trivial install script that bootstraps Postgres/ClickHouse/Kafka migrations. Vendoring the whole tree would mean:

• ~3 MB of YAML + Python config we do not own
• Every minor upgrade becomes a giant merge-conflict
• The license/attribution surface grows substantially
• Coolify's git-pull-on-deploy gets slower

Instead, we reference the upstream repo at the pinned ref and clone it at deploy time inside our own wrapper. Our repository only contains the overlay we want on top of upstream:

• docker-compose.override.yml — Compose merge-overlay (network, volumes, Traefik labels, env-passthrough)
• sentry/sentry.conf.py — Python config overlay (single-org, no-signup, OTLP, no external symbol sources)
• relay/config.yml — Relay config with OTLP ingest enabled
• backup/ — sidecar container that backs up Postgres + ClickHouse to S3
• install.sh — wrapper that clones upstream + applies overlays + invokes the upstream installer

Clone strategy (what install.sh does)

The wrapper performs the equivalent of:

# Clone exactly the pinned tag into infra/sentry/upstream/self-hosted/,
# shallow + single-branch to keep the working tree lean.
git clone \
  --branch 25.12.1 \
  --depth 1 \
  --single-branch \
  https://github.com/getsentry/self-hosted.git \
  infra/sentry/upstream/self-hosted

After cloning, the wrapper:

1. Copies infra/sentry/docker-compose.override.yml → infra/sentry/upstream/self-hosted/docker-compose.override.yml
2. Copies infra/sentry/sentry/sentry.conf.py → infra/sentry/upstream/self-hosted/sentry/sentry.conf.py (overwrites the upstream default; ours is a strict superset)
3. Copies infra/sentry/relay/config.yml → infra/sentry/upstream/self-hosted/relay/config.yml
4. Sources .env from the repo root of infra/sentry/
5. Executes the upstream installer in non-interactive mode: ./install.sh --skip-user-prompt --no-report-self-hosted-issues

The infra/sentry/upstream/ directory is git-ignored (see .gitignore), so the cloned tree never lands in our history. The empty placeholder upstream/.gitkeep exists so the directory is present in the repo for a fresh checkout but stays empty until the first install.sh run.

Update procedure

To upgrade to a newer 25.x.y patch:

1. Update the tag in this file (UPSTREAM.md) and in install.sh.
2. Read upstream release notes for any sentry.conf.py migrations and sync our overlay if upstream renamed/removed any setting we override.
3. On staging, run ./install.sh again. The upstream installer is idempotent: it detects the existing volumes, runs only the new migrations, then restarts services.
4. Smoke-test (web-UI, event-ingest, OTLP-ingest, backup container).
5. Commit the bumped tag + overlay deltas as one commit.

For the eventual 25.x → 26.x jump see the runbook in docs/observability/sentry-selfhost.md — that one is a manual disaster-recovery-grade operation, not a ./install.sh re-run.