# Upstream Pin: `getsentry/self-hosted` ## Pinned Version | Field | Value | | --- | --- | | Upstream repo | | | 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: ```bash # 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.