92 lines
4.6 KiB
Markdown
92 lines
4.6 KiB
Markdown
# Upstream Pin: `getsentry/self-hosted`
|
|
|
|
## Pinned Version
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Upstream repo | <https://github.com/getsentry/self-hosted> |
|
|
| Pinned git tag | **`25.12.1`** |
|
|
| Pinned commit | **`5c9794c9b1fda551f38515f85d56ec298371d060`** |
|
|
| 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
|
|
|
|
## Fetch strategy (what `install.sh` does)
|
|
|
|
The tag is release metadata only. The wrapper executes the immutable commit
|
|
that the tag resolved to when this pin was reviewed:
|
|
|
|
```bash
|
|
git -C infra/sentry/upstream/self-hosted init
|
|
git -C infra/sentry/upstream/self-hosted remote add origin https://github.com/getsentry/self-hosted.git
|
|
git -C infra/sentry/upstream/self-hosted fetch --depth 1 origin 5c9794c9b1fda551f38515f85d56ec298371d060
|
|
git -C infra/sentry/upstream/self-hosted checkout --detach 5c9794c9b1fda551f38515f85d56ec298371d060
|
|
```
|
|
|
|
The installer then compares `rev-parse HEAD` with the pinned commit and aborts
|
|
on any mismatch. Moving or replacing the upstream tag therefore cannot change
|
|
the executed installer.
|
|
|
|
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. Resolve and review the new tag, then update both tag and immutable commit 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.
|