polar-local-environment

ローカル環境スキル

dev docker CLI を通じて Polar のローカル開発環境の管理を支援します。ローカルスタックの起動、停止、デバッグ、または仕組みの確認に使用します。

2 部構成モデル

dev docker は、複数のワークツリーで大規模なインフラを共有できるよう、スタックを意図的に分割しています。

• 共有インフラ — マシンごとに 1 つ。Docker プロジェクトは polar-shared： postgres、redis、minio、tinybird、およびオプションの prometheus/grafana。Postgres と redis はホストポートを公開しません。MinIO はブラウザーからのアップロード用に 9000/9001 を公開します。ホストポートのないサービスには dev docker exec <service> ... を使用します。
• インスタンスごとのアプリスタック — ワークツリーごとに 1 つ。プロジェクトは polar-app-<N>：api、worker、web。ホストポートを公開するのは api と web のみで、インスタンスごとにポート番号がずれるため、ワークツリー同士で競合しません。

これを理解しておくと、最もよくある混乱を避けられます。データベース用の localhost:5432 はありません（データベースは共有スタック内にあり、dev docker exec db ... を通じてアクセスします）。MinIO はブラウザーからのアップロードとコンソールへのアクセス用に 9000/9001 を公開します。

インスタンスの自動検出

dev docker は現在のワークツリーのインスタンスを自動検出するため、-i が必要になることはほとんどありません。優先順位は次のとおりです。

1. dev/docker/.env.docker で固定された POLAR_DOCKER_INSTANCE（dev docker set-instance N）
2. ワークツリー間で共有されるレジストリ（~/.config/polar/docker-instances.json）
3. それ以外の場合は、最も小さい空き番号。その後、登録済みの番号

dev docker ports を実行すると、解決されたインスタンスと URL を確認できます（ツール向けには --json を追加します）。このワークツリーを Claude Code のプレビューに接続するには、dev docker launch-json を実行します。正しいポートを設定したインスタンスごとの .claude/launch.json が書き込まれます（Git の追跡対象外のため、set-instance の後に再生成してください）。

使用する場面

• ローカル環境の起動／停止／再起動
• ログの表示、または起動しないサービスのデバッグ
• 複数の分離されたワークツリーインスタンスの並行実行
• サービスアーキテクチャの把握、またはサービスの実際のポートの特定
• コンテナや初回起動時のエラーの診断

クイックリファレンス

タスク	コマンド
スタック全体を起動（バックグラウンド）	dev docker up -d
起動し、正常な状態になるまで待機	dev docker up -d --wait
フォアグラウンドで起動（ログをストリーミング）	dev docker up --no-detach
新しいベースイメージを取得して再ビルド	dev docker up -b --pull -d
このインスタンスのポート／URLを表示	dev docker ports（ツール向けには --json）
Claude Code のプレビュー設定を書き込む	dev docker launch-json
アプリスタックを停止	dev docker down
アプリと共有インフラを停止	dev docker down --all
ログを追跡	dev docker logs -f [service]
ログを出力して終了	dev docker logs --no-follow [service]
ステータス	dev docker ps
サービスを再起動	dev docker restart <service>
サービスのシェルに入る	dev docker shell <service>
サービス内で単発のコマンドを実行	dev docker exec <service> <cmd>
このインスタンスをリセット	dev docker cleanup -f
共有データをすべて消去	dev docker cleanup --all -f
すべてのインスタンスを一覧表示	dev docker list
モニタリングを有効にして起動	dev docker up --monitoring -d

サービス

サービス	プロジェクト	ホストポート（インスタンス 0 / N）	備考
api	polar-app-<N>	8000 / 8100+N	FastAPI；/healthz ヘルスチェック
web	polar-app-<N>	3000 / 3100+N	Next.js；ヘルスチェックあり
worker	polar-app-<N>	なし	バックグラウンドジョブ
db	polar-shared	なし（exec）	PostgreSQL；DB は polar_dev_<N>
redis	polar-shared	なし（exec）	Redis の DB インデックス = N
minio	polar-shared	9000、9001	S3；バケットは polar-s3-<N>；コンソールは 9001
tinybird	polar-shared	なし（exec）	アナリティクス
prometheus / grafana	polar-shared	なし（exec）	--monitoring のみ

現在のワークツリーで使われている正確なホストポートを確認するには、dev docker ports を実行します。

インスタンスのポートマッピング

ホストポートが割り当てられるのは api と web のみです。インスタンス 1～99 では、Port = Base + Instance です（api の Base は 8100、web の Base は 3100）。インスタンス 0 では、従来の 8000 / 3000 を使用します。

インスタンス	API	Web
0	8000	3000
1	8101	3101
2	8102	3102
5	8105	3105

それ以外のものはすべてインスタンスごとに分かれますが、ホストポートは割り当てられません。データベースは polar_dev_<N>、Redis の DB インデックスは <N>、バケットは polar-s3-<N> / polar-s3-public-<N> です。dev docker exec <service> または docker exec polar-shared-<service>-1 を使ってアクセスしてください。

ルール一覧

ルール	カテゴリ	説明
service-architecture	参照	サービスの詳細、ポート、ヘルスチェック
start-environment	運用	スタックの起動（フラグ、--wait、--pull）
stop-environment	運用	停止とクリーンアップ（アプリと共有サービス）
manage-instances	運用	並行作業用のワークツリーインスタンス
view-logs	デバッグ	サービスログの表示
shell-and-workflows	運用	シェルへのアクセスと一般的な開発ワークフロー
troubleshooting	デバッグ	よくあるエラーと解決方法
payment-testing	運用	ログインコード、Stripe の Webhook、バックオフィス