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

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:

Reset the database

Git worktrees

Each worktree has its own .venv. When you create a worktree with git worktree add, a post-checkout hook runs devenv sync in it to set up the dev environment. Otherwise run devenv sync once in the new worktree, then direnv allow to validate and activate it.

Troubleshooting Decision Tree

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