docs(skills): add setup-dev skill for dev environment setup (#108744)

HazAT · mchen-sentry · commit 392e0e032113 · 2026-02-24T11:38:22.000-08:00
## Summary Add a comprehensive agent skill (`.claude/skills/setup-dev/`) that guides engineers through setting up the Sentry dev environment from scratch — from a bare machine to a running dev server. ## Motivation Setting up Sentry locally is a complex, multi-step process that takes 30-45 minutes and involves many tools (devenv, devservices, direnv, Docker runtimes, etc.). The existing documentation is spread across multiple sources, and several common pitfalls aren't well-documented: - **direnv hangs silently** when the Docker runtime isn't running - **Chicken-and-egg problem**: direnv checks for node/sentry before `devenv sync` can install them - **OrbStack users get Colima errors** because scripts hardcode the Colima socket path - **`devservices up` takes 5-10 minutes** on first run (Docker image pulls) with no warning - **Database needs `sentry upgrade`**, not just `migrate` — without seeding, every page 500s - **Kafka topic warnings** on first boot look alarming but are normal - **Blank white screen** without the Cookie Sync extension, with no hint about what's wrong This skill encodes all of that hard-won knowledge so AI agents can walk engineers through setup smoothly. ## What's included ``` .claude/skills/setup-dev/ ├── SKILL.md # Full 7-step walkthrough with troubleshooting └── references/ └── orbstack-fix.md # How to patch devservices.py for OrbStack support ``` The skill covers: 1. **State detection** — checks what's already installed to skip completed steps 2. **Prerequisites** — Xcode CLT, Homebrew, Docker runtime (OrbStack vs Colima with tradeoffs table) 3. **devenv setup** — installation, shell config, version verification 4. **Bootstrap** — first-time machine setup 5. **Environment sync** — with workarounds for direnv hang and chicken-and-egg issues 6. **Services** — time expectations, OrbStack socket fix, database seeding, superuser creation 7. **Dev server** — what to expect on startup, Kafka warnings, Cookie Sync extension Plus a troubleshooting decision tree mapping symptoms → causes → fixes. Integrates with the AL MCP docs server for deeper troubleshooting when available. ## Related - #108740 — fixes the OrbStack socket detection in `devservices.py` itself
diff --git a/.agents/skills/setup-dev/SKILL.md b/.agents/skills/setup-dev/SKILL.md
@@ -0,0 +1,323 @@
+---
+name: setup-dev
+description: Set up and manage the Sentry development environment using devenv. Handles fresh setup, updating existing environments, starting dev services, and troubleshooting. Use when asked to "set up sentry", "setup dev environment", "get sentry running", "start dev server", "devenv setup", "devservices not working", "sentry won't start", or any development environment issue.
+---
+
+# 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](https://github.com/getsentry/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:
+
+```bash
+# 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 2>/dev/null
+
+# Check devenv version (outdated versions cause failures)
+devenv --version 2>/dev/null || ~/.local/share/sentry-devenv/bin/devenv --version 2>/dev/null
+
+# Check Docker runtime
+docker context ls 2>/dev/null
+docker info --format '{{.Name}}' 2>/dev/null
+
+# Check OrbStack
+which orbctl 2>/dev/null && orbctl status 2>/dev/null
+
+# Check Colima
+which colima 2>/dev/null && colima status 2>/dev/null
+
+# Check direnv
+which direnv 2>/dev/null
+
+# Check if repo is already set up
+ls .venv/bin/sentry 2>/dev/null && ls node_modules/.bin 2>/dev/null
+```
+
+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
+
+```bash
+xcode-select -p 2>/dev/null || xcode-select --install
+```
+
+If not installed, the user must complete the interactive install dialog (~10 min). Wait for it.
+
+### Homebrew
+
+```bash
+which brew || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+### Docker Runtime — OrbStack or Colima
+
+Ask the user which they prefer. Explain the tradeoffs:
+
+| Runtime      | Pros                                                   | Cons                                                     |
+| ------------ | ------------------------------------------------------ | -------------------------------------------------------- |
+| **Colima**   | Official Sentry recommendation, all scripts support it | Can have DNS issues on WiFi changes                      |
+| **OrbStack** | Faster, lower resource usage, better UI                | Some Sentry scripts assume Colima — may need workarounds |
+
+**If choosing OrbStack:**
+
+```bash
+brew install --cask 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
+
+```bash
+# For external (non-Sentry-employee) contributors:
+# export SENTRY_EXTERNAL_CONTRIBUTOR=1
+
+curl -fsSL https://raw.githubusercontent.com/getsentry/devenv/main/install-devenv.sh | bash
+```
+
+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:
+
+```bash
+# Check if already configured
+grep -q "sentry-devenv" ~/.zshrc 2>/dev/null || grep -q "sentry-devenv" ~/.bashrc 2>/dev/null
+```
+
+If not configured, add to the appropriate shell config (`~/.zshrc` for zsh, `~/.bashrc` for bash):
+
+```bash
+# devenv
+export PATH="$HOME/.local/share/sentry-devenv/bin:$PATH"
+
+# direnv
+eval "$(direnv hook zsh)"   # or: eval "$(direnv hook 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:
+
+```bash
+devenv --version
+```
+
+If the version is old (e.g., < 1.22), upgrade:
+
+```bash
+devenv update
+```
+
+If `devenv update` itself fails because the version is too old, reinstall:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/getsentry/devenv/main/install-devenv.sh | bash
+```
+
+## Step 4: Bootstrap (First Time Only)
+
+For a completely fresh setup, run bootstrap first:
+
+```bash
+devenv bootstrap
+```
+
+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:
+
+```
+direnv: ([...]/direnv export zsh) is taking a while to execute. Use CTRL-C to give up.
+```
+
+**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:**
+
+```bash
+~/.local/share/sentry-devenv/bin/devenv sync
+```
+
+Or if devenv is on PATH:
+
+```bash
+devenv sync
+```
+
+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
+
+```bash
+devservices up
+```
+
+**⏱️ 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:
+
+```
+Make sure colima is running. Run `devenv colima start`.
+```
+
+...but the user is using OrbStack, the `devservices.py` command is checking for the Colima socket only. Check `src/sentry/runner/commands/devservices.py`:
+
+```bash
+grep -n "colima\|docker.sock\|orbstack" 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 `${CLAUDE_SKILL_ROOT}/references/orbstack-fix.md` for the exact pattern.
+
+### Then: Seed the Database
+
+If this is a first-time setup, the database needs seeding:
+
+```bash
+.venv/bin/sentry upgrade --noinput
+```
+
+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
+
+```bash
+.venv/bin/sentry createuser --superuser --email admin@sentry.io --password admin --no-input
+```
+
+## Step 7: Start the Dev Server
+
+```bash
+devservices serve
+```
+
+Or directly:
+
+```bash
+.venv/bin/sentry devserver
+```
+
+### What to Expect on Startup
+
+**Kafka topic warnings are normal.** On first start, you'll see many lines like:
+
+```
+[WARNING] sentry.batching-kafka-consumer: Topic 'taskworker' or its partitions are not ready, retrying...
+```
+
+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:
+
+```bash
+cd ~/Projects/sentry    # (or wherever the repo lives)
+devservices up           # start background services (~30s)
+devservices serve        # start dev server
+# → http://dev.sentry.localhost:8000
+```
+
+After pulling new code:
+
+```bash
+devenv sync              # update dependencies + migrations (2-5 min)
+```
+
+## Troubleshooting Decision Tree
+
+| Symptom                                         | Likely Cause                              | Fix                                                  |
+| ----------------------------------------------- | ----------------------------------------- | ---------------------------------------------------- |
+| direnv hangs                                    | Docker runtime not running                | Start OrbStack / Colima                              |
+| `devenv sync` fails with version error          | Outdated devenv                           | `devenv update` or reinstall                         |
+| `devservices up` says "colima not running"      | Using OrbStack, script only checks Colima | Patch `devservices.py` — see Step 6                  |
+| Server 500s on every page                       | DB not seeded                             | `.venv/bin/sentry upgrade --noinput`                 |
+| `relation "sentry_organization" does not exist` | Migrations not run                        | `.venv/bin/sentry upgrade --noinput`                 |
+| White/blank screen in browser                   | Cookie Sync extension missing             | Install the Chrome extension                         |
+| Kafka topic warnings on startup                 | Normal first-boot behavior                | Wait 30-60 seconds                                   |
+| Port already in use                             | Stale containers                          | `docker rm -f $(docker ps -aq)` then retry           |
+| Everything is broken                            | Nuclear option                            | `devservices purge && devenv sync && devservices up` |
+| DNS failures in Docker                          | Colima DNS stale                          | `devenv doctor` or `devenv colima restart`           |
+
+For deeper troubleshooting, use the AL MCP if available ([devinfra-mcp](https://github.com/getsentry/devinfra-mcp)):
+
+```
+al_search_docs(query="<symptom keywords>")
+al_read_doc(path="devenv/troubleshooting.md", query="<specific issue>")
+```
diff --git a/.agents/skills/setup-dev/references/orbstack-fix.md b/.agents/skills/setup-dev/references/orbstack-fix.md
@@ -0,0 +1,52 @@
+# OrbStack Docker Socket Fix
+
+When `devservices serve` or `sentry devserver` fails with "Make sure colima is running" for OrbStack users, the issue is in `src/sentry/runner/commands/devservices.py`.
+
+## The Problem
+
+The `check_docker_daemon_running()` function checks for a Docker socket at a hardcoded Colima path. When using OrbStack, that path doesn't exist, so it falls through to the error message telling the user to start Colima.
+
+## The Fix Pattern
+
+Replace the single hardcoded socket path with a function that checks multiple paths:
+
+```python
+import os
+import sys
+
+if sys.platform == "darwin":
+    _DOCKER_SOCKET_PATHS = [
+        os.path.expanduser("~/.colima/default/docker.sock"),
+        os.path.expanduser("~/.orbstack/run/docker.sock"),
+        "/var/run/docker.sock",
+    ]
+else:
+    _DOCKER_SOCKET_PATHS = ["/var/run/docker.sock"]
+
+
+def _find_docker_socket() -> str:
+    for path in _DOCKER_SOCKET_PATHS:
+        if os.path.exists(path):
+            return path
+    return ""
+```
+
+Then update `check_docker_daemon_running()` to use `_find_docker_socket()` and update the error message:
+
+```python
+def check_docker_daemon_running():
+    socket_path = _find_docker_socket()
+    if not socket_path:
+        raise SystemExit(
+            "Make sure your Docker runtime is running (Colima, OrbStack, or Docker Desktop)."
+        )
+    # ... rest of the check using socket_path
+```
+
+## Verify
+
+After patching:
+
+1. Remove any symlinks: `rm -f ~/.colima/default/docker.sock` (if it was a symlink to OrbStack)
+2. Ensure OrbStack is running: `orbctl status`
+3. Run: `.venv/bin/sentry devserver` — should detect OrbStack's socket automatically
