Sentry Deployment & Usage Guide

1. Prerequisites

System Requirements

OS: Linux, macOS, or Windows (WSL2 recommended)
Memory: Minimum 8GB RAM (16GB+ recommended for production)
Disk: 20GB+ free space
Docker: Docker 20.10+ and Docker Compose 2.0+ (required for dependencies)
Python: 3.11.x (check runtime requirements)
Node.js: 18.x+ (for frontend builds)
Git: 2.28+

Required Services (via Docker)

Sentry requires these external services:

PostgreSQL 14+
Redis 6.2+
Kafka (for event streaming)
ClickHouse (via Snuba for event storage)
ZooKeeper (Kafka dependency)

Accounts & Keys

GitHub account (for OAuth integrations)
Optional: Google Cloud/AWS account (for file storage backends)
Optional: SMTP credentials (for email notifications)

2. Installation

Clone Repository

git clone https://github.com/getsentry/sentry.git
cd sentry

Python Environment Setup

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or: .venv\Scripts\activate  # Windows

# Install Python dependencies
pip install -e ".[dev]"

Frontend Dependencies

# Install Node dependencies
npm install
yarn install  # Alternative

Install Development Services

# Start all required services (PostgreSQL, Redis, Kafka, ClickHouse, etc.)
sentry devservices up

# Verify services status
sentry devservices status

3. Configuration

Initial Configuration

# Generate initial configuration
sentry init

# This creates:
# - ~/.sentry/config.yml (main configuration)
# - ~/.sentry/sentry.conf.py (Python settings)

Key Configuration Files

config.yml (~/.sentry/config.yml):

system.url-prefix: 'http://localhost:8000'
system.admin-email: 'admin@example.com'
system.secret-key: 'your-secret-key-here'  # Generate with: openssl rand -hex 32

# Database
redis.clusters:
  default:
    hosts:
      0:
        host: 127.0.0.1
        port: 6379

# File storage (local filesystem for dev)
filestore.backend: 'filesystem'
filestore.options:
  location: '/tmp/sentry-files'

# Mail (use console backend for dev)
mail.backend: 'console'

sentry.conf.py (~/.sentry/sentry.conf.py):

import os

# Database
DATABASES = {
    'default': {
        'ENGINE': 'sentry.db.postgres',
        'NAME': 'sentry',
        'USER': 'postgres',
        'PASSWORD': '',
        'HOST': '127.0.0.1',
        'PORT': '5432',
    }
}

# Redis
SENTRY_REDIS_HOST = '127.0.0.1'
SENTRY_REDIS_PORT = 6379

# Features
SENTRY_FEATURES = {
    'auth:register': True,
    'organizations:performance-view': True,
    'organizations:discover': True,
}

Environment Variables

# Development
export SENTRY_CONF=~/.sentry
export SENTRY_ENVIRONMENT=development
export SENTRY_DEVSERVICES_DSN=false  # Disable external reporting

# Performance
export SENTRY_WORKERS=4
export C_FORCE_ROOT=true  # If running Celery as root (dev only)

4. Build & Run

Database Setup

# Run migrations
sentry upgrade

# Create superuser
sentry createuser --email admin@example.com --password yourpassword --superuser

Build Frontend Assets

# Development (with hot reload)
yarn dev

# Production build
yarn build

Run Development Server

# Start all services (if not already running)
sentry devservices up

# Run web server
sentry run web

# In separate terminals, run:
sentry run worker          # Background workers
sentry run cron            # Periodic tasks
sentry run consumer        # Event ingestion

Access Application

Development Workflow

# Run tests
pytest tests/sentry/api/
pytest tests/sentry/integrations/

# Linting
pre-commit run --all-files

# Type checking
mypy src/sentry

5. Deployment

Option A: Self-Hosted (Docker Compose) - Recommended for Small Teams

Use the official self-hosted repository:

git clone https://github.com/getsentry/self-hosted.git
cd self-hosted
./install.sh
docker compose up -d

Production Configuration:

Update sentry/config.yml with real SMTP settings
Configure external storage (S3/GCS) for filestore
Set up proper PostgreSQL backups
Configure Redis persistence
Set up Kafka/ClickHouse monitoring

Option B: Kubernetes (Production Scale)

For high availability deployments:

Use the Sentry Helm Chart
Requirements: Kubernetes 1.24+, Helm 3.12+
Minimum nodes: 3 (8 CPU, 32GB RAM each)

helm repo add sentry https://sentry-kubernetes.github.io/charts
helm install sentry sentry/sentry \
  --set sentry.web.replicas=3 \
  --set sentry.worker.replicas=5 \
  --set kafka.enabled=true \
  --set clickhouse.enabled=true

Option C: SaaS (Sentry.io)

For most teams, use the managed service at https://sentry.io to avoid infrastructure complexity.

Production Checklist

Change default secret keys
Configure HTTPS/TLS
Set up SMTP for email notifications
Configure backup strategy (PostgreSQL + ClickHouse)
Set up monitoring (Prometheus/Grafana)
Configure CDN for static assets
Enable rate limiting
Set up log rotation

6. Troubleshooting

Service Startup Issues

Kafka/ClickHouse won't start:

# Check Docker resources (needs 8GB+ RAM)
docker system prune -a  # Clean old volumes if stuck
sentry devservices down
sentry devservices up redis postgres kafka clickhouse

Database connection errors:

# Reset database
dropdb sentry
createdb -E utf-8 sentry
sentry upgrade

Build Issues

Node modules conflicts:

rm -rf node_modules
yarn cache clean
yarn install

Python dependency conflicts:

pip install --force-reinstall -e ".[dev]"

Runtime Errors

Celery worker errors:

Check Redis connectivity: redis-cli ping
Verify Kafka topics exist: kafka-topics.sh --list --bootstrap-server localhost:9092

Event ingestion not working:

# Check Relay logs
docker logs sentry_relay

# Verify snuba consumer
sentry run consumer --consumer-type errors

Performance issues:

Increase SENTRY_WORKERS environment variable
Check PostgreSQL connection pooling
Verify ClickHouse queries aren't timing out

Common Migration Failures

# If upgrade fails, try:
sentry django migrate --fake-initial
sentry upgrade --noinput

Getting Help

Documentation: https://docs.sentry.io/
GitHub Issues: https://github.com/getsentry/sentry/issues
Discord: https://discord.gg/PXa5Apfe7K
Development docs: https://docs.sentry.io/internal/contributing/

How to Deploy & Use getsentry/sentry