VPS Tutorials
Self-host Sentry on a VPS (2026): Docker, HTTPS, SDKs, alerts and recovery
Deploy Sentry Self-Hosted 26.8.0 on Ubuntu with errors-only, Caddy HTTPS and SMTP. Configure JavaScript/Python SDKs, source maps and releases, reduce alert noise, and verify full backups and upgrades.

Production exceptions are difficult when you cannot identify the release, user, request and environment involved. Sentry collects stacks, breadcrumbs, releases and contextual data, groups repeated events into issues and notifies owners through email or integrations.
This guide uses Ubuntu 24.04, Sentry Self-Hosted 26.8.0, Docker Compose and Caddy. It covers sizing, errors-only mode, HTTPS, SMTP, JavaScript/Python SDKs, source maps, releases, noise control, offline recovery and required upgrade stops.
Version context: the source described
26.8.0as the latest release on September 5, 2026. That date is historical. Its verified release removes seven old metrics containers, switches Redis-compatible service to Valkey and includes security fixes. Pin a reviewed supported Git tag; do not use nightly or unattended production upgrades.
Two constraints matter:
- Official Self-Hosted targets low-volume deployments and evaluation; it is not a maintenance-free equivalent of the SaaS.
- PostgreSQL, ClickHouse, Kafka, Valkey, Relay, Snuba, Symbolicator and SeaweedFS demand substantially more resources and operations work than a blog.
Consider self-hosting when:
- Events must remain outside a third-party SaaS.
- Your team controls retention and storage location.
- Internal services cannot reach public Sentry.
- Someone owns Docker, databases, backups and alerts.
- Low-volume JavaScript, Python, Java or mobile projects need one error service.
For one small project without response and recovery capacity, hosted service can cost less overall. Self-hosting trades subscription/data-transfer constraints for VPS, backup, upgrades and incident work.
| Tool | Best at | Input | Does not replace |
|---|---|---|---|
| Sentry | Exceptions, stacks, releases and tracing | SDK events | Full logs and infrastructure metrics |
| Loki/OpenObserve | Log search and retention | stdout, files, agents | SDK error context |
| Prometheus/Grafana | Numeric trends | Metrics | Detailed exception stacks |
| Uptime Kuma | External availability and certificates | HTTP/TCP/DNS probes | Internal error diagnosis |
An uptime probe detects an unreachable site, Sentry identifies the failing release/line, and logs supply surrounding requests. Start with the Uptime Kuma guide if external availability checks are missing.
The 26.8.0 installer has version-specific resource checks:
| Mode | Installer floor | Practical starting point | Use |
|---|---|---|---|
errors-only | 2 vCPU, about 7 GB Docker-available RAM | 4 vCPU / 12 GB / 100 GB NVMe | Error monitoring |
feature-complete | 4 vCPU, about 14 GB Docker-available RAM | 4–8 vCPU / 16–32 GB / 200 GB NVMe | Performance, Replay and more |
The source's official reference is 4 cores, 16 GB RAM and 20 GB free disk. Free-space minimum is not sustained capacity: events, attachments, replay, profiles, ClickHouse and Kafka grow. Plan 100–200 GB NVMe and measure volume and retention.
An 8 GB host leaves very little headroom even for errors-only. Heavy swap does not replace RAM; sustained swapping is particularly unsuitable for ClickHouse/Kafka.
Monthly SDK uploads are approximately average event size × daily event count × 30. The original formula is:
月上行流量 ≈ 平均事件大小 × 每日事件数 × 30
20 KB per event and 100,000 events/day produces roughly 60 GB/month before attachments, replay, source maps and protocol overhead. Use stable connectivity and sufficient traffic allowance. Disk and RAM often become bottlenecks first.
Set sampling, filter expected exceptions and exclude sensitive data. A repeated-error loop can otherwise flood the service within minutes.
Use the official getsentry/self-hosted repository. SDKs reach Caddy over HTTPS, then local nginx/Relay and the event-processing stack:
应用 SDK
↓ HTTPS 443
Caddy(宿主机 TLS)
↓ 127.0.0.1:9000
官方 nginx / Relay
↓
Sentry Web + Worker + Snuba
↓
PostgreSQL / ClickHouse / Kafka / Valkey / SeaweedFS
Only Caddy is public. Built-in nginx binds to 127.0.0.1:9000; databases and queues stay on Docker networks.
Point a hostname such as sentry.example.com at the VPS. Permit:
22/tcp: restricted SSH administration.80/tcp: certificates and redirects.443/tcpand443/udp: HTTPS/HTTP3.9000/tcp: loopback only, no public firewall opening.- No public database, ClickHouse, Kafka or Valkey mappings.
export SENTRY_DOMAIN="sentry.example.com"
getent ahosts "$SENTRY_DOMAIN"
curl -4 https://ifconfig.me
Publish AAAA only with working IPv6. Also verify actual Docker bindings and cloud rules, not just the host firewall.
sudo apt-get update
sudo apt-get install -y ca-certificates curl git jq rsync
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker version
sudo docker compose version
This version requires Docker 19.03.6+, Compose 2.32.2+ and Bash 4.4+. Check installed versions. Install openssl too if absent, since secret generation below needs it. See the production Compose guide for health, logs and limits.
nproc
free -h
df -h /
df -i /
uname -a
sysctl vm.max_map_count
Configure vm.max_map_count:
echo 'vm.max_map_count=262144' | sudo tee /etc/sysctl.d/90-sentry.conf
sudo sysctl --system
sysctl vm.max_map_count
Put Docker data on sufficiently sized NVMe. Moving /var/lib/docker requires downtime and a verified backup; do not casually change daemon storage paths after deployment.
sudo install -d -o "$USER" -g "$USER" -m 0750 /opt/sentry
cd /opt/sentry
git clone https://github.com/getsentry/self-hosted.git
cd self-hosted
git fetch --tags
git checkout 26.8.0
git status --short
git describe --tags --exact-match
The final command should show 26.8.0. Avoid master/nightly, whose defaults can change without a reviewed upgrade.
Choose errors-only for errors, issues, releases and basic alerts. Use feature-complete for supported performance, replay, profiling and other optional features.
Keep overrides in .env.custom, rather than duplicating all of .env and freezing old defaults:
cd /opt/sentry/self-hosted
LAUNCHPAD_SECRET="$(openssl rand -hex 32)"
umask 077
cat >.env.custom <<EOF
COMPOSE_PROFILES=errors-only
SENTRY_BIND=127.0.0.1:9000
SENTRY_EVENT_RETENTION_DAYS=30
SENTRY_MAIL_HOST=example.com
SENTRY_TASKWORKER_CONCURRENCY=2
LAUNCHPAD_RPC_SHARED_SECRET=${LAUNCHPAD_SECRET}
EOF
unset LAUNCHPAD_SECRET
chmod 600 .env.custom
For full features, change COMPOSE_PROFILES to feature-complete. Tune taskworker concurrency to available RAM. Keep this dotenv file valid shell assignments: the official installer sources it as well as passing it to Compose.
Check the tag and changes first:
cd /opt/sentry/self-hosted
git status --short
sudo ./install.sh --no-report-self-hosted-issues
It checks resources, creates volumes/configuration/secrets, builds local images, initializes storage and migrates databases. First installation can exceed ten minutes.
Load both environment files when starting:
cd /opt/sentry/self-hosted
sudo docker compose --env-file .env --env-file .env.custom up --wait
sudo docker compose --env-file .env --env-file .env.custom ps
sudo docker compose --env-file .env --env-file .env.custom logs --tail=200 web relay nginx
Investigate a container in starting through its health and dependencies before restarting the whole stack repeatedly.
Installation creates sentry/config.yml from sentry/config.example.yml. Edit the real configuration:
mail.backend: "smtp"
mail.host: "smtp.example.com"
mail.port: 587
mail.username: "[email protected]"
mail.password: "replace-with-app-password"
mail.use-tls: true
system.url-prefix: "https://sentry.example.com"
system.internal-url-prefix: "http://web:9000"
Choose only one of mail.use-tls and mail.use-ssl. Protect SMTP credentials:
cd /opt/sentry/self-hosted
sudo chmod 600 sentry/config.yml
sudo docker compose --env-file .env --env-file .env.custom up -d
A bind-mounted file change does not itself recreate running containers. After editing live configuration, use sudo docker compose --env-file .env --env-file .env.custom up -d --force-recreate in a maintenance window, and verify the services actually reload it. Check container-readable ownership before applying restrictive file permissions.
Since 26.6.0, new email addresses require verification. Use functioning SMTP, send a test and then invite users; a dummy backend is unsuitable.
sudo apt-get install -y debian-keyring debian-archive-keyring apt-transport-https curl gnupg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list >/dev/null
sudo apt-get update
sudo apt-get install -y caddy
Create /etc/caddy/Caddyfile:
sentry.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:9000 {
header_up Host {host}
header_up X-Real-IP {remote_host}
header_up X-Forwarded-For {remote_host}
header_up X-Forwarded-Proto {scheme}
transport http {
read_timeout 90s
write_timeout 90s
}
}
log {
output file /var/log/caddy/sentry-access.log
format json
}
}
Ensure the Caddy service can write its log directory, for example with sudo install -d -o caddy -g caddy -m 0750 /var/log/caddy, then validate/reload:
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo systemctl status caddy --no-pager
curl -fsSI https://sentry.example.com/
See the Caddy HTTPS guide.
cd /opt/sentry/self-hosted
sudo ./sentry-admin.sh createuser
Supply email/password and create a superuser, then open https://sentry.example.com and create an organization/project. Use strong passwords and two-factor authentication. SDKs and CI must not use administrator tokens.
set -euo pipefail
cd /opt/sentry/self-hosted
curl -fsS http://127.0.0.1:9000/_health/
curl -fsSI https://sentry.example.com/
sudo docker compose --env-file .env --env-file .env.custom ps
sudo docker compose --env-file .env --env-file .env.custom logs --since=10m --tail=300 web relay snuba-api
Local health should return ok. A working page without events requires Relay, Kafka consumers, Snuba and ClickHouse investigation, not just web health.
Copy the project DSN from Settings → Client Keys:
npm install @sentry/browser
import * as Sentry from "@sentry/browser";
Sentry.init({
dsn: "https://[email protected]/PROJECT_ID",
environment: "production",
release: "[email protected]",
tracesSampleRate: 0.1,
beforeSend(event) {
if (event.request?.headers) {
delete event.request.headers.Authorization;
delete event.request.headers.Cookie;
}
return event;
},
});
Send a test exception:
try {
throw new Error("sentry-self-hosted-test");
} catch (error) {
Sentry.captureException(error);
}
The sample's 0.1 tracing rate belongs to a deployment supporting performance. With errors-only, set tracesSampleRate: 0; use traces_sample_rate=0 for Python too. Never default production tracing to tracesSampleRate: 1.0. Size sampling to load and investigative value. The sample only removes two header spellings: define broader redaction for URLs, query fields, user data and case variants.
Use your application's virtual environment on Ubuntu 24.04 rather than modifying externally managed system Python:
sudo apt-get install -y python3-venv
python3 -m venv .venv
. .venv/bin/activate
python3 -m pip install --upgrade sentry-sdk
import os
import sentry_sdk
sentry_sdk.init(
dsn=os.environ["SENTRY_DSN"],
environment=os.getenv("APP_ENV", "production"),
release=os.getenv("APP_RELEASE", "[email protected]"),
traces_sample_rate=0.1,
send_default_pii=False,
)
def divide(a: int, b: int) -> float:
return a / b
divide(1, 0)
Confirm environment, release and stack in the issue. A DSN is not an administrator password, but manage it per project; actual Auth Tokens belong in a secret manager.
Source maps make minified bundle stacks readable. SDK release must exactly match the uploaded release:
name: build-and-upload-sourcemaps
on:
push:
tags:
- "v*"
permissions:
contents: read
jobs:
build:
runs-on: ubuntu-latest
env:
SENTRY_URL: "https://sentry.example.com/"
SENTRY_ORG: "example-org"
SENTRY_PROJECT: "web"
SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: "22"
cache: npm
- run: npm ci
- run: npm run build
- name: Upload source maps
run: |
set -euo pipefail
VERSION="web@${GITHUB_REF_NAME}"
npx --yes @sentry/cli releases new "$VERSION"
npx --yes @sentry/cli sourcemaps inject ./dist
npx --yes @sentry/cli sourcemaps upload --release "$VERSION" ./dist
npx --yes @sentry/cli releases finalize "$VERSION"
This source workflow creates web@${GITHUB_REF_NAME}, while the SDK example hardcodes [email protected]. Set the build's release variable before npm run build and have SDK configuration read that same value. Inject debug IDs, upload the maps and deploy that exact modified dist directory; rebuilding after injection breaks artifact correspondence. Enable source-map generation in the build.
Pin Actions/tool versions according to your supply-chain policy. Give the token only necessary release permissions and never print it.
Build, release identity and upload belong to one pipeline:
pipeline {
agent any
environment {
SENTRY_URL = 'https://sentry.example.com/'
SENTRY_ORG = 'example-org'
SENTRY_PROJECT = 'web'
}
stages {
stage('Build and upload source maps') {
steps {
withCredentials([string(credentialsId: 'sentry-auth-token', variable: 'SENTRY_AUTH_TOKEN')]) {
sh '''
set -euo pipefail
npm ci
npm run build
VERSION="web@${GIT_COMMIT}"
npx --yes @sentry/cli releases new "$VERSION"
npx --yes @sentry/cli sourcemaps inject ./dist
npx --yes @sentry/cli sourcemaps upload --release "$VERSION" ./dist
npx --yes @sentry/cli releases finalize "$VERSION"
'''
}
}
}
}
}
Set the same web@${GIT_COMMIT} identity in the build before compiling, inject/upload maps, then deploy those exact files. Run the Bash-specific source shell with Bash or use POSIX-compatible shell flags. See the Jenkins guide for credentials and agents.
- P1: new production faults, many affected users or a sudden error increase; notify immediately.
- P2: regressions, repeated issues or critical transaction failures; aggregate for 5–15 minutes.
- P3: development/test or low-frequency errors; include in daily summaries.
Give each issue an owner, environment, release and response action. Avoid sending every new issue to one channel. Filter browser-extension noise, crawlers, deliberate cancellations and expected business exceptions in the SDK; use inbound filters and sampling server-side. Observe filter matches before discarding events broadly.
Use consistent identities:
[email protected]+abc1234
[email protected]+def5678
Separate production and staging. Mark releases on deployment and use the correct identity after rollback. SonarQube complements this by checking static quality before merging; Sentry observes runtime failures.
Define:
- Allowed event fields.
- Redaction of cookies, authorization, phone numbers and email.
- Access to the production organization.
- Retention period.
- Revocation of departed users and tokens.
- Whether the deployment region meets cross-border and regulatory requirements.
Defaults do not establish compliance with your own policy. Combine beforeSend, send_default_pii=False, server-side scrubbing and least privilege.
SENTRY_EVENT_RETENTION_DAYS=30 in .env.custom affects scheduled cleanup. Short retention reduces some storage growth but does not cover every log, cache and volume.
cd /opt/sentry/self-hosted
sudo docker system df -v
sudo docker volume ls
df -h /var/lib/docker
df -i /var/lib/docker
sudo docker compose --env-file .env --env-file .env.custom logs --since=24h --tail=1000 sentry-cleanup
Do not run unreviewed docker system prune --volumes: persistent volumes contain events, attachments and databases.
- Public
https://sentry.example.comand local/_health/. - Critical container health, restarts and OOM.
- CPU, RAM, load, disk, inodes and I/O wait.
- PostgreSQL, ClickHouse, Kafka and Valkey capacity.
- Relay intake and consumer lag.
- Caddy certificates, 5xx and latency.
- Backup completion and off-host copies.
Uptime Kuma can probe HTTPS, but send a test event too: a healthy page can hide a blocked event pipeline.
scripts/backup.sh exports logical global configuration to sentry/backup.json. It is not a complete event backup or a consistent snapshot of all stores.
Include at least:
- Repository/configuration for the pinned tag.
sentry-data,sentry-postgres,sentry-clickhouse,sentry-kafka,sentry-redisandsentry-seaweedfs.- Required profile, taskbroker and other persistent volumes.
- Caddy configuration and recovery instructions.
- Checksums, encryption and off-host copies.
The source exports configuration, lists mounted volumes, shuts down and archives each one:
#!/usr/bin/env bash
set -euo pipefail
cd /opt/sentry/self-hosted
STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
BACKUP_DIR="/srv/backups/sentry/${STAMP}"
COMPOSE=(sudo docker compose --env-file .env --env-file .env.custom)
sudo install -d -m 0700 "$BACKUP_DIR/volumes"
sudo ./scripts/backup.sh --no-report-self-hosted-issues
sudo cp sentry/backup.json "$BACKUP_DIR/backup.json"
mapfile -t CONTAINERS < <("${COMPOSE[@]}" ps -q)
test "${#CONTAINERS[@]}" -gt 0
mapfile -t VOLUMES < <(
sudo docker inspect "${CONTAINERS[@]}" \
--format '{{range .Mounts}}{{if eq .Type "volume"}}{{println .Name}}{{end}}{{end}}' |
sort -u
)
test "${#VOLUMES[@]}" -gt 0
printf '%s\n' "${VOLUMES[@]}" | sudo tee "$BACKUP_DIR/volumes.list" >/dev/null
"${COMPOSE[@]}" down
sudo tar -C /opt/sentry -czf "$BACKUP_DIR/self-hosted-config.tar.gz" \
--exclude='self-hosted/.git' \
self-hosted
for volume in "${VOLUMES[@]}"; do
safe_name="${volume//\//_}"
sudo docker run --rm \
-v "${volume}:/source:ro" \
-v "$BACKUP_DIR/volumes:/backup" \
alpine:3.22 \
tar -C /source -czf "/backup/${safe_name}.tar.gz" .
done
sudo find "$BACKUP_DIR" -type f ! -name SHA256SUMS -print0 |
sort -z |
sudo xargs -0 sha256sum |
sudo tee "$BACKUP_DIR/SHA256SUMS" >/dev/null
"${COMPOSE[@]}" up --wait
echo "Backup complete: $BACKUP_DIR"
Replace it with this root-run version for the documented local-volume layout. It also inventories existing declared volumes, records the exact commit, captures Caddy, protects secrets and arms restart handling before stopping. Its JSON inspection errors propagate instead of being hidden in process substitution:
#!/usr/bin/env bash
set -euo pipefail
test "$(id -u)" -eq 0
cd /opt/sentry/self-hosted
umask 077
exec 9>/run/lock/sentry-backup.lock
flock -n 9
SENTRY_BACKUP="/srv/backups/sentry/$(date -u +%Y%m%dT%H%M%SZ)"
install -d -m 0700 "$SENTRY_BACKUP/volumes"
sentry_compose() {
docker compose --env-file .env --env-file .env.custom "$@"
}
./scripts/backup.sh --no-report-self-hosted-issues
cp sentry/backup.json "$SENTRY_BACKUP/backup.json"
git rev-parse HEAD >"$SENTRY_BACKUP/deployment-commit.txt"
sentry_compose config --format json >"$SENTRY_BACKUP/compose.private.json"
mapfile -t SENTRY_CONTAINERS < <(sentry_compose ps -q)
test "${#SENTRY_CONTAINERS[@]}" -gt 0
docker inspect "${SENTRY_CONTAINERS[@]}" >"$SENTRY_BACKUP/mounts.private.json"
jq -r '.[] | .Mounts[] | select(.Type == "volume") | .Name' \
"$SENTRY_BACKUP/mounts.private.json" >"$SENTRY_BACKUP/volume-candidates.list"
while IFS= read -r SENTRY_VOLUME; do
docker volume inspect "$SENTRY_VOLUME" >/dev/null
done <"$SENTRY_BACKUP/volume-candidates.list"
jq -r '.volumes // {} | to_entries[] | .value.name // empty' \
"$SENTRY_BACKUP/compose.private.json" >>"$SENTRY_BACKUP/volume-candidates.list"
sort -u "$SENTRY_BACKUP/volume-candidates.list" >"$SENTRY_BACKUP/volume-candidates.sorted"
: >"$SENTRY_BACKUP/volumes.list"
while IFS= read -r SENTRY_VOLUME; do
if docker volume inspect "$SENTRY_VOLUME" >/dev/null 2>&1; then
printf '%s\n' "$SENTRY_VOLUME" >>"$SENTRY_BACKUP/volumes.list"
fi
done <"$SENTRY_BACKUP/volume-candidates.sorted"
test -s "$SENTRY_BACKUP/volumes.list"
docker pull alpine:3.22 >/dev/null
trap 'sentry_compose up -d >&2' EXIT
sentry_compose stop
tar -C /opt/sentry -czf "$SENTRY_BACKUP/self-hosted-config.tar.gz" \
--exclude='self-hosted/.git' self-hosted
tar -C /etc -czf "$SENTRY_BACKUP/caddy-config.tar.gz" caddy
while IFS= read -r SENTRY_VOLUME; do
docker run --rm \
-v "$SENTRY_VOLUME:/source:ro" \
-v "$SENTRY_BACKUP/volumes:/backup" \
alpine:3.22 tar -C /source -czf "/backup/$SENTRY_VOLUME.tar.gz" .
done <"$SENTRY_BACKUP/volumes.list"
(
cd "$SENTRY_BACKUP"
find . -type f ! -name SHA256SUMS -print0 | sort -z | \
xargs -0 sha256sum >SHA256SUMS
sha256sum -c SHA256SUMS
)
sentry_compose up --wait
trap - EXIT
touch "$SENTRY_BACKUP/COMPLETE"
chmod -R go-rwx "$SENTRY_BACKUP"
printf 'Backup complete: %s\n' "$SENTRY_BACKUP"
Save it as /opt/sentry/backup-offline.sh and test on a nonproduction clone. Validate the volume inventory against required stores; external services need their own coordinated backup. Accept only a verified COMPLETE backup and confirm service health after restart. Encrypt/copy off-host: a local archive cannot survive loss of the same disk. See the restic/rclone recovery drill.
At least monthly on an isolated VPS:
- Install compatible Docker/Compose.
- Check out the recorded Sentry tag/commit; pull pinned remote images and rebuild required local images from that source.
- Verify
SHA256SUMS. - Create empty volumes from
volumes.list. - Extract matching archives into them, preserving ownership.
- Restore
self-hostedconfiguration. - Start the full selected profile.
- Log in, open historical issues and send a new event.
- Verify SMTP, alerts and source maps.
- Record RTO, RPO and failures.
Keep the restored instance isolated until accepted so it cannot compete with production for the same DSN traffic.
Sentry uses CalVer. The official list includes 26.5.0 and 26.7.0 as mandatory stops; older deployments can need earlier stops too. Review the complete current list and each intervening release before moving to the selected target.
set -euo pipefail
cd /opt/sentry/self-hosted
git fetch --tags
git status --short
git tag --sort=-version:refname | head -n 20
sudo /opt/sentry/backup-offline.sh
For a route through this source's versions, upgrade/validate 26.5.0, then 26.7.0, then 26.8.0, merging configuration changes at each stop:
cd /opt/sentry/self-hosted
git checkout 26.8.0
git diff HEAD@{1} -- .env docker-compose.yml sentry/config.example.yml sentry/sentry.conf.example.py
sudo ./install.sh --no-report-self-hosted-issues --minimize-downtime
sudo docker compose --env-file .env --env-file .env.custom ps
curl -fsS http://127.0.0.1:9000/_health/
The example's --minimize-downtime flag is explicitly experimental: it can leave a partial upgrade or fail to reload some configuration. Prefer the normal installer in a planned maintenance window unless that option has been rehearsed for your exact upgrade.
26.8.0 removes seven metrics-related containers; fix stale references in docker-compose.override.yml. It also changes the Redis-compatible image to Valkey, so monitors must not infer health from the old image name.
Running git checkout for an old tag does not undo database migrations. A recoverable rollback is:
- Stop the failed new version.
- Isolate its current volumes and retain diagnostic evidence.
- Restore all required pre-upgrade volumes/configuration from one point.
- Check out the original tag.
- Start and verify the event pipeline.
- Prevent simultaneous SDK writes to both instances.
A VPS snapshot needs a tested consistent recovery procedure before it can be called a rollback plan.
The pinned full profile checks roughly 4 cores/14 GB; errors-only checks roughly 2 cores/7 GB. Increase resources or change the profile with host headroom, rather than bypassing checks.
Check DSN, DNS and system time, then follow the pipeline:
cd /opt/sentry/self-hosted
sudo docker compose --env-file .env --env-file .env.custom logs --since=15m --tail=500 relay
sudo docker compose --env-file .env --env-file .env.custom logs --since=15m --tail=500 kafka
sudo docker compose --env-file .env --env-file .env.custom logs --since=15m --tail=500 snuba-consumer-errors
sudo docker compose --env-file .env --env-file .env.custom logs --since=15m --tail=500 clickhouse
Use docker compose config --services with both environment files to find actual profile services. An errors-only deployment may omit services from someone else's full-stack example.
curl -v http://127.0.0.1:9000/_health/
sudo ss -lntp | grep ':9000'
sudo journalctl -u caddy --since '15 minutes ago' --no-pager
An unreachable local 9000 points at Sentry/nginx; investigate Caddy when local service works but public access fails.
Check mail.backend, SMTP host/port/TLS, credentials, sender domain and processing logs. Prefer authenticated 465/587 if the provider blocks 25.
Check event floods, retention, lag and cleanup. Stop abnormal SDK volume, back up and follow component-specific recovery; do not delete live database directories or volumes.
Read release notes. Removed metrics services require updates to custom overrides, monitors and hardcoded backup lists.
- Reviewed official tag
26.8.0, no master/nightly. - Profile selected deliberately.
- Resources exceed installer floors with host headroom.
-
SENTRY_BINDbinds only to127.0.0.1:9000. - Public Caddy HTTPS works without public backend ports.
-
system.url-prefixmatches the domain. - SMTP, verification and alerts tested.
- JavaScript/Python exceptions arrive in the intended project.
- Release, environment and source maps match.
- Redaction and sampling configured.
- Disk, containers, lag and certificates monitored.
- Backup covers every required volume and configuration.
- Isolated restoration tested.
- Upgrade route includes all hard stops.
For 26.8.0, installer floors are about 2 cores/7 GB for errors-only and 4 cores/14 GB for full features. The source's official reference is 4 cores/16 GB/20 GB free disk. Include growth and host resources: start around 12 GB for errors-only or 16–32 GB for full features, then measure.
Errors-only may start with little headroom; it is not a reliable production recommendation. Full features fail the resource check. Increase RAM, reduce event volume/retention or consider hosted service.
Check the exact repository's LICENSE.md and terms. Downloadable self-hosting does not by itself imply a traditional permissive license. Review permitted use before commercial modification or offering a service.
Web/nginx health does not prove Relay → Kafka → consumers → ClickHouse. Check DSN/time and send a uniquely named test exception while following that chain.
No. Cleanup takes time, and Kafka, attachments, caches and other volumes have separate lifecycles. Observe sentry-cleanup, component capacity and disk trends.
No. Its backup.json logical export is not a coordinated snapshot of PostgreSQL, ClickHouse, Kafka, SeaweedFS and all persistence. Use a maintenance window, complete backups, off-host copies and restore tests.
Beyond running install.sh, choose the right profile, pin releases, expose HTTPS, align source maps and control volume/privacy/storage. Send a real application's test exception with a unique release, then restore a complete backup in isolation. Both pipelines need verification for maintainable monitoring.