setup-dev

Set Up Sentry Development Environment

Walk the user through getting Sentry running locally. The full process from a bare machine takes 30-45 minutes — most of that is downloading dependencies and Docker images. Set expectations clearly at each step.

AL MCP: If the al MCP server is available, use al_search_docs and al_read_doc for detailed troubleshooting. The AL docs cover devenv, devservices, and common issues in depth. The AL server is part of the devinfra-mcp project — see that repo for setup instructions if the server isn't configured yet. The SSE endpoint is configured in .pi/mcp.json (pi) or .mcp.json / .cursor/mcp.json (Claude Code / Cursor).

Step 1: Detect Current State

Before doing anything, assess what's already installed. Run all of these:

# Check OS
uname -s && uname -m
 
# Check shell
echo $SHELL
 
# Check if devenv exists
which devenv 2>/dev/null || ls ~/.local/share/sentry-devenv/bin/devenv

Based on results, skip to the appropriate step. If everything is installed, jump to Step 6.

Step 2: Install Prerequisites (macOS)

Xcode Command Line Tools

If not installed, the user must complete the interactive install dialog (~10 min). Wait for it.

Homebrew

Docker Runtime — OrbStack or Colima

Ask the user which they prefer. Explain the tradeoffs:

If choosing OrbStack:

Then start OrbStack from Applications. Verify: docker info

If choosing Colima: Colima gets installed by devenv bootstrap — no separate step needed.

Important: Do NOT run Docker Desktop alongside either runtime — it causes conflicts.

Step 3: Install devenv

This installs to ~/.local/share/sentry-devenv/bin/devenv.

Shell Configuration

The user's shell MUST have devenv on PATH and direnv hooked in. Check and fix:

If not configured, add to the appropriate shell config (~/.zshrc for zsh, ~/.bashrc for bash):

Tell the user to restart their terminal (or source ~/.zshrc) after this change.

Verify devenv Version

Minimum version changes frequently. If devenv is already installed, check it's not outdated:

If the version is old (e.g., < 1.22), upgrade:

If devenv update itself fails because the version is too old, reinstall:

Step 4: Bootstrap (First Time Only)

For a completely fresh setup, run bootstrap first:

This is interactive (~5 min) — it prompts for SSH keys, coderoot directory, etc. It installs Homebrew, Colima, Docker CLI, and direnv.

After bootstrap completes, close and reopen the terminal.

Step 5: Sync the Environment

This is the longest step. Tell the user:

This will take 10-20 minutes on first run. It installs Python, Node, all pip/npm dependencies, and runs database migrations. Subsequent syncs are much faster (2-5 min).

If direnv hangs

The .envrc runs Docker checks. If the Docker runtime isn't running, direnv will hang. Symptoms:

Fix: Start the Docker runtime first:

• OrbStack: Open OrbStack.app or open -a OrbStack
• Colima: devenv colima start

Then direnv allow again.

Chicken-and-Egg Problem

direnv checks node version and sentry installation. On a fresh setup, these don't exist yet, so direnv will fail. This is normal. Bypass direnv and run devenv sync directly:

Or if devenv is on PATH:

After sync completes, direnv allow should succeed.

If devenv sync fails

Common causes:

1. Outdated devenv — devenv update or reinstall
2. Docker not running — start OrbStack/Colima first
3. Network issues — retry; some downloads are large

Run devenv doctor for automated diagnosis.

Step 6: Start Services

First: Start Docker Images

⏱️ First run: 5-10 minutes. It pulls many Docker images (PostgreSQL, Redis, Kafka, ClickHouse, Snuba, Relay, etc.). This is a one-time cost. Tell the user:

This is downloading all the Docker images Sentry needs. It looks like a lot — that's normal. Subsequent starts take ~30 seconds.

Subsequent runs: ~30 seconds.

OrbStack Socket Issue

If devservices up or devservices serve fails with:

...but the user is using OrbStack, the devservices.py command is checking for the Colima socket only. Check src/sentry/runner/commands/devservices.py:

The _find_docker_socket() function needs to check multiple socket paths. On macOS it should try, in order:

1. ~/.colima/default/docker.sock (Colima)
2. ~/.orbstack/run/docker.sock (OrbStack)
3. /var/run/docker.sock (Docker Desktop / default)

If only Colima is checked, patch it to support all runtimes. Read references/orbstack-fix.md for the exact pattern.

Then: Seed the Database

If this is a first-time setup, the database needs seeding:

This runs all Django migrations AND creates default data (organizations, roles, projects). Without this, the dev server will 500 on every page.

Do NOT just run sentry django migrate — that only runs migrations without seeding the required default data.

Create Superuser

Step 7: Start the Dev Server

Or directly:

What to Expect on Startup

Kafka topic warnings are normal. On first start, you'll see many lines like:

These settle down after 30-60 seconds as Kafka auto-creates topics. Don't panic.

Access the Dev Server

• URL: http://dev.sentry.localhost:8000
• Login: admin@sentry.io / admin

Required: Sentry Cookie Sync Extension

Without this extension, the UI shows a blank white screen. Install it:

https://chromewebstore.google.com/detail/sentry-cookie-sync/kchlmkcdfohlmobgojmipoppgpedhijh

This syncs auth cookies between sentry.io and dev.sentry.localhost. It's not optional.

Day-to-Day Commands

After initial setup, the daily workflow is:

After pulling new code:

Troubleshooting Decision Tree

For deeper troubleshooting, use the AL MCP if available (devinfra-mcp):