setup-dev

Sentry 開発環境のセットアップ

ユーザーが Sentry をローカルで実行できるようにする手順を案内します。まっさらなマシンからの全工程には 30～45 分かかります。その大半は依存関係と Docker イメージのダウンロードです。各ステップで期待値を明確に伝えてください。

AL MCP: al MCP サーバーが利用可能な場合は、詳細なトラブルシューティングのために al_search_docs と al_read_doc を使用してください。AL ドキュメントでは、devenv、devservices、よくある問題について詳しく解説しています。AL サーバーは devinfra-mcp プロジェクトの一部です。サーバーがまだ設定されていない場合は、そのリポジトリのセットアップ手順を参照してください。SSE エンドポイントは .pi/mcp.json (pi) または .mcp.json / .cursor/mcp.json (Claude Code / Cursor) で設定します。

ステップ 1: 現在の状態を検出する

何かを行う前に、すでに何がインストールされているかを確認します。次のコマンドをすべて実行してください:

# 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

結果に基づいて、適切なステップに進んでください。すべてインストール済みであれば、ステップ 6 に進みます。

ステップ 2: 前提条件のインストール (macOS)

Xcode コマンドラインツール

xcode-select -p 2>/dev/null || xcode-select --install

インストールされていない場合、ユーザーは対話式のインストールダイアログを完了する必要があります (約 10 分)。完了するまで待ってください。

Homebrew

which brew || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Docker ランタイム — OrbStack または Colima

どちらを希望するかをユーザーに尋ねてください。トレードオフを説明します:

ランタイム	長所	短所
Colima	Sentry 公式の推奨。すべてのスクリプトが対応している	WiFi の切り替え時に DNS の問題が発生することがある
OrbStack	高速で、リソース使用量が少なく、UI も優れている	一部の Sentry スクリプトは Colima を前提としているため、回避策が必要になることがある

OrbStack を選ぶ場合:

brew install --cask orbstack

その後、アプリケーションから OrbStack を起動します。確認: docker info

Colima を選ぶ場合: Colima は devenv bootstrap によってインストールされるため、別途のステップは不要です。

重要: どちらのランタイムであっても、Docker Desktop を併用して実行しないでください。競合が発生します。

ステップ 3: devenv のインストール

# For external (non-Sentry-employee) contributors:
# export SENTRY_EXTERNAL_CONTRIBUTOR=1

curl -fsSL https://raw.githubusercontent.com/getsentry/devenv/main/install-devenv.sh | bash

これは ~/.local/share/sentry-devenv/bin/devenv にインストールされます。

シェルの設定

ユーザーのシェルは、devenv が PATH に通っており、direnv がフックされている必要があります。確認して修正してください:

# Check if already configured
grep -q "sentry-devenv" ~/.zshrc 2>/dev/null || grep -q "sentry-devenv" ~/.bashrc 2>/dev/null

設定されていない場合は、適切なシェル設定ファイル (zsh なら ~/.zshrc、bash なら ~/.bashrc) に追加します:

# devenv
export PATH="$HOME/.local/share/sentry-devenv/bin:$PATH"

# direnv
eval "$(direnv hook zsh)"   # or: eval "$(direnv hook bash)"

この変更の後、ユーザーにターミナルを再起動するよう伝えてください (または source ~/.zshrc を実行)。

devenv バージョンの確認

最小バージョンは頻繁に変わります。devenv がすでにインストールされている場合は、古くなっていないか確認してください:

devenv --version

バージョンが古い場合 (例: 1.22 未満)、アップグレードします:

devenv update

バージョンが古すぎて devenv update 自体が失敗する場合は、再インストールします:

curl -fsSL https://raw.githubusercontent.com/getsentry/devenv/main/install-devenv.sh | bash

ステップ 4: ブートストラップ (初回のみ)

完全に新規のセットアップでは、まずブートストラップを実行します:

devenv bootstrap

これは対話式です (約 5 分)。SSH キー、coderoot ディレクトリなどを尋ねられます。Homebrew、Colima、Docker CLI、direnv をインストールします。

ブートストラップが完了したら、ターミナルを閉じて再度開いてください。

ステップ 5: 環境の同期

これが最も長いステップです。ユーザーに伝えてください:

初回実行時は 10～20 分かかります。Python、Node、すべての pip/npm 依存関係をインストールし、データベースマイグレーションを実行します。以降の同期ははるかに高速です (2～5 分)。

direnv がハングする場合

.envrc は Docker のチェックを実行します。Docker ランタイムが起動していないと、direnv はハングします。症状:

direnv: ([...]/direnv export zsh) is taking a while to execute. Use CTRL-C to give up.

修正: まず Docker ランタイムを起動します:

• OrbStack: OrbStack.app を開くか、open -a OrbStack を実行
• Colima: devenv colima start

その後、再度 direnv allow を実行します。

鶏と卵の問題

direnv は node のバージョンと sentry のインストールをチェックします。新規セットアップではこれらがまだ存在しないため、direnv は失敗します。これは正常です。direnv をバイパスして、devenv sync を直接実行してください:

~/.local/share/sentry-devenv/bin/devenv sync

または、devenv が PATH に通っている場合:

devenv sync

同期が完了すれば、direnv allow は成功するはずです。

devenv sync が失敗する場合

よくある原因:

1. devenv が古い — devenv update または再インストール
2. Docker が起動していない — まず OrbStack/Colima を起動してください
3. ネットワークの問題 — 再試行してください。一部のダウンロードは大容量です

自動診断には devenv doctor を実行してください。

ステップ 6: サービスの起動

まず: Docker イメージの起動

devservices up

⏱️ 初回実行: 5〜10 分。 多くの Docker イメージ (PostgreSQL、Redis、Kafka、ClickHouse、Snuba、Relay など) を取得します。これは一度だけのコストです。ユーザーに次のように伝えてください:

Sentry が必要とするすべての Docker イメージをダウンロードしています。大量に見えますが、これは正常です。以降の起動は約 30 秒で完了します。

以降の実行: 約 30 秒。

OrbStack のソケットの問題

devservices up または devservices serve が次のエラーで失敗する場合:

Make sure colima is running. Run `devenv colima start`.

...しかしユーザーが OrbStack を使用している場合、devservices.py コマンドは Colima のソケットのみをチェックしています。src/sentry/runner/commands/devservices.py を確認してください:

grep -n "colima\|docker.sock\|orbstack" src/sentry/runner/commands/devservices.py

_find_docker_socket() 関数は複数のソケットパスをチェックする必要があります。macOS では、次の順序で試す必要があります:

1. ~/.colima/default/docker.sock (Colima)
2. ~/.orbstack/run/docker.sock (OrbStack)
3. /var/run/docker.sock (Docker Desktop / デフォルト)

Colima のみがチェックされている場合は、すべてのランタイムをサポートするようにパッチを適用してください。正確なパターンについては references/orbstack-fix.md を参照してください。

次に: データベースのシード

初回セットアップの場合、データベースのシードが必要です:

.venv/bin/sentry upgrade --noinput

これはすべての Django マイグレーションを実行し、かつデフォルトデータ (組織、ロール、プロジェクト) を作成します。これがないと、開発サーバーはすべてのページで 500 を返します。

単に sentry django migrate を実行しないでください — これはマイグレーションを実行するだけで、必要なデフォルトデータをシードしません。

スーパーユーザーの作成

.venv/bin/sentry createuser --superuser --email [email protected] --password admin --no-input

ステップ 7: 開発サーバーの起動

devservices serve

または直接:

.venv/bin/sentry devserver

起動時に予想されること

Kafka トピックの警告は正常です。 初回起動時には、次のような行が多数表示されます:

[WARNING] sentry.batching-kafka-consumer: Topic 'taskworker' or its partitions are not ready, retrying...

これらは Kafka がトピックを自動作成するにつれて、30〜60 秒後に落ち着きます。慌てないでください。

開発サーバーへのアクセス

• URL: http://dev.sentry.localhost:8000
• ログイン: [email protected] / admin

必須: Sentry Cookie Sync 拡張機能

この拡張機能がないと、UI は真っ白な画面を表示します。 インストールしてください:

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

これは sentry.io と dev.sentry.localhost の間で認証 Cookie を同期します。これは任意ではありません。

日々のコマンド

初期セットアップ後、日々のワークフローは次のとおりです:

cd ~/Projects/sentry    # (or wherever the repo lives)
devservices up           # start background services (~30s)
devservices serve        # start dev server
# → http://dev.sentry.localhost:8000

新しいコードをプルした後:

devenv sync              # update dependencies + migrations (2-5 min)

データベースのリセット

make reset-db

Git ワークツリー

各ワークツリーには独自の .venv があります。git worktree add でワークツリーを作成すると、post-checkout フックがその中で devenv sync を実行して開発環境をセットアップします。そうでない場合は、新しいワークツリーで一度 devenv sync を実行し、次に direnv allow を実行して検証および有効化してください。

トラブルシューティングの判断ツリー

症状	考えられる原因	対処法
direnv がハングする	Docker ランタイムが起動していない	OrbStack / Colima を起動してください
devenv sync がバージョンエラーで失敗する	devenv が古い	devenv update または再インストール
devservices up が「colima not running」と表示する	OrbStack を使用しているが、スクリプトは Colima しか確認しない	devservices.py を修正 — 手順 6 を参照
すべてのページでサーバーが 500 エラーを返す	DB がシードされていない	.venv/bin/sentry upgrade --noinput
relation "sentry_organization" does not exist	マイグレーションが実行されていない	.venv/bin/sentry upgrade --noinput
ブラウザで画面が白くなる/何も表示されない	Cookie Sync 拡張機能がない	Chrome 拡張機能をインストールしてください
起動時に Kafka トピックの警告が出る	初回起動時の正常な動作	30〜60 秒待ってください
ポートがすでに使用されている	古いコンテナが残っている	docker rm -f $(docker ps -aq) を実行して再試行
すべてが壊れている	最終手段	devservices purge && devenv sync && devservices up
Docker 内で DNS 障害が発生する	Colima の DNS が古い	devenv doctor または devenv colima restart

より詳細なトラブルシューティングには、利用可能であれば AL MCP を使用してください（devinfra-mcp）:

al_search_docs(query="<symptom keywords>")
al_read_doc(path="devenv/troubleshooting.md", query="<specific issue>")