Self‑Hosted Sentry Monitoring: Detailed Docker Compose Deployment and Troubleshooting

Self‑Hosted Sentry Overview

Sentry provides its source code and a minimal self‑hosted repository that can be run out‑of‑the‑box for simple use cases. The recommended stack uses Docker, Docker Compose, and Bash‑based install/upgrade scripts.

Installation

Download the latest self‑hosted repository and run ./install.sh. The script creates a baseline configuration, then start Sentry with docker-compose up -d. By default Sentry listens on port 9000 and is reachable at http://127.0.0.1:9000.

Latest release: https://github.com/getsentry/self-hosted/releases/latest

Configuration

sentry/config.yml – generated from sentry/config.example.yml. Common options include: system.url-prefix – set after installation via the welcome screen. mail.* – basic SMTP configuration (exim4 is provided by default). GitHub, Slack and other integrations.

sentry/sentry.conf.py – advanced settings generated from sentry/sentry.conf.example.py. Example file: https://github.com/getsentry/self-hosted/blob/master/sentry/sentry.conf.example.py

Environment variables are defined in .env. To avoid Git‑tracked changes, create a .env.custom file and start containers with docker-compose --env-file /path/to/.env.custom up -d.

Custom CA roots are placed under the certificates directory and the containers are restarted.

After changing configuration, restart services with docker-compose restart web worker cron sentry-cleanup (or simply docker-compose restart ).

Production Recommendations

Bind Sentry to a dedicated domain or sub‑domain behind a load balancer that terminates SSL/TLS. Health checks should target the /_health/ endpoint, expecting HTTP 200 or 500 with error details.

All services run as single‑node containers (Kafka, Redis, etc.). Larger workloads may require a Kubernetes cluster with more RAM and disk.

Release and Upgrade Cycle

Sentry follows a CalVer monthly release schedule, publishing a new version on the 15th of each month. Details: https://calver.org/#scheme and the repository’s release page: https://github.com/getsentry/self-hosted/releases. CalVer aligns the self‑hosted version closely with the SaaS version.

Upgrade Procedure

Upgrade by downloading the desired version, replacing the repository contents, and re‑running ./install.sh. Configuration files may need updating; check the example files for new options. An experimental --minimize-downtime flag can reduce downtime, but the risk is borne by the operator.

Version‑Specific Upgrade Paths

From any version < 9.1.2 → 9.1.2 → 21.5.0 → 21.6.3 → latest.

<your.sentry.version> -> 9.1.2 -> 21.5.0 -> 21.6.3 -> latest

From 9.1.2 → 21.5.0 → 21.6.3 → latest.

<your.sentry.version> -> 21.5.0 -> 21.6.3 -> latest

From 21.6.3 → latest.

<your.sentry.version> -> 21.6.3 -> latest

Any version ≥ 21.6.3 can upgrade directly to the latest.

Nightly Builds

Nightly builds of the master branch are provided for Sentry and its supporting projects (Snuba, Relay, Symbolicator). These builds are generally stable but may contain breaking changes; use at your own risk.

Backup and Restore

Quick Backup

Export a fast backup (excluding event data) with:

docker-compose run --rm -T -e SENTRY_LOG_LEVEL=CRITICAL web export > sentry/backup.json

Omit -T or the log‑level flag and the output will contain log lines that must be stripped.

Restore

Place the backup file under /etc/sentry in the repository and run:

docker-compose run --rm -T web import /etc/sentry/backup.json

A zero exit code indicates success.

For a full restore, back up all Docker volumes prefixed with sentry- (e.g., sentry-data , sentry-postgres , sentry-redis , etc.).

Full Backup Strategy

Back up the following volumes to preserve all persistent data:

sentry-data

sentry-postgres

sentry-redis

sentry-zookeeper

sentry-kafka

sentry-clickhouse

sentry-symbolicator

Project‑specific volumes (named sentry_self_hosted_sentry‑*) should also be backed up if needed.

Custom CA Roots

From Sentry 21.8.0 onward, add a private CA certificate to the certificates directory, run update-ca-certificates inside the container, and restart containers to apply the custom CA.

Email Configuration

The self‑hosted instance ships with an exim4 SMTP server. Set mail.from in config.yml and SENTRY_MAIL_HOST in .env to point to your FQDN. To use an external SMTP server, configure the mail.* section in config.yml and comment out the default mail.host: 'smtp' line.

Geolocation

Sentry can use MaxMind’s free GeoLite2‑City database via the geoipupdate tool. Register a MaxMind account, create a GeoIP.conf with your credentials, and the next install.sh run will download the database. Verify the integration by checking “Errors by Country” in the Dashboards or the IP column in Session History.

Example GeoIP.conf content:

AccountID 012345
LicenseKey foobarbazbuz
EditionIDs GeoLite2-City

After the next restart of the relay and web services, the country code should appear in the UI.

Single Sign‑On (SSO)

Sentry supports two SSO approaches: middleware proxy (e.g., SAML2) that marks the request as authenticated, and third‑party authentication pipelines (OAuth).

SAML2 via Middleware

From Sentry 20.6.0 onward, SAML2 is built‑in. For older versions, add the following line to sentry/requirements.txt before running ./install.sh:

sentry-auth-saml2@https://github.com/getsentry/sentry-auth-saml2/archive/master.zip#egg=sentry-auth-saml2

Configure the URL prefix in config.yml as described in the official SAML documentation: https://docs.sentry.io/accounts/sso/#saml2-identity-provider.

OAuth‑Based SSO

Enabling SSO makes it the sole login method.

Google Auth – add to sentry/config.yaml:

auth-google.client-id: '<client id>'
auth-google.client-secret: '<client secret>'

GitHub Auth – create a GitHub App, then set in sentry/sentry.conf.py and sentry/config.yaml:

GITHUB_APP_ID="<App ID>)"
GITHUB_API_SECRET="<Client secret>)"
GITHUB_REQUIRE_VERIFIED_EMAIL = True  # optional but recommended

Custom Provider

The SSO API is still unstable; you can build a provider by referencing the code under src/sentry/auth/providers in the main Sentry repository: https://github.com/getsentry/sentry/tree/master/src/sentry/auth/providers.

Troubleshooting

View service logs with docker-compose logs <service_name> -f -t. Use the following sections for common components.

Kafka

Common error:

Exception: KafkaError{code=OFFSET_OUT_OF_RANGE,val=1,str="Broker: Offset out of range"}

. Causes include disk/memory pressure, long processing times causing retention expiry, or time sync issues after restarts.

Recovery steps:

List consumer groups:

docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --list

Describe the group (e.g., snuba-consumers):

docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --group snuba-consumers --describe

Optionally dry‑run a reset:

docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --group snuba-consumers --topic events --reset-offsets --to-latest --dry-run

Execute the reset:

docker-compose run --rm kafka kafka-consumer-groups --bootstrap-server kafka:9092 --group snuba-consumers --topic events --reset-offsets --to-latest --execute

Hard‑core option: delete Kafka and Zookeeper volumes and reinstall:

Stop the instance: docker-compose down --volumes Remove volumes: docker volume rm sentry-kafka and docker volume rm sentry-zookeeper Run ./install.sh again.

Start with docker-compose up -d.

Redis

Redis serves both as a data store and Celery broker. From Sentry 20.10.1 onward, performance improvements were added. If issues persist, consider scaling Redis or switching the Celery broker to RabbitMQ.

Workers

Backlog warnings (e.g., “Background workers haven’t checked in recently…”) indicate insufficient worker capacity. Add dedicated workers via docker-compose.override.yml with a specific queue, for example:

worker1:
  <<: *sentry_defaults
  command: run worker -Q events.process_event

Postgres

The node_nodestore table can grow quickly. Use the cleanup command to keep only recent data, then run pg-repack to reclaim space. Example script:

# Keep only the last 7 days of nodestore data
docker-compose run -T web cleanup --days 7 -m nodestore -l debug
# Install pg-repack and repack the table
docker-compose run -T postgres bash -c "apt update && apt install -y --no-install-recommends postgresql-9.6-repack && su postgres -c 'pg_repack -E info -t nodestore_node'"

Note that disk usage spikes temporarily during the repack operation.

General Help

Community assistance is available on the Sentry forum (https://forum.sentry.io/) or the GitHub issue tracker (https://github.com/getsentry/self-hosted/issues/new/choose). Provide installation logs, service logs, and the Sentry version when reporting issues.