setting-up-devbox

PostHog 開発ボックスのセットアップ

開発ボックスは、PostHog の開発に使用する EC2 上の Coder ワークスペースです。 hogli devbox:* を使って操作し、これらのコマンドの機能を再実装しないでください。 新しいボックスには、master ブランチのリポジトリが ~/posthog にあり、依存関係は事前に準備され、Claude Code がインストールされています。 現在のフラグは hogli devbox:<command> --help で確認できます。 このスキルでは、操作の順序とヘルプテキストに記載されていない内容を説明します。

ボックスの用途はさまざまです。一般的な開発用のシェルやエディターとして使う場合、ローカルのチェックアウト先となるリモートターゲットとして使う場合、または実行中の PostHog アプリのホストとして使う場合があります。 ユーザーがどの用途を望んでいるかを確認し、アプリを求められない限り PostHog スタックを起動しないでください。

ボックスを取得する

このチェックリストをコピーして、進捗を記録してください。

- [ ] 1. hogli devbox:doctor: the tailnet and control plane checks are ok
- [ ] 2. hogli devbox:setup has run on this machine
- [ ] 3. hogli devbox:start: the box is running
- [ ] 4. The user is connected the way they asked for
- [ ] 5. hogli devbox:stop when the user is done

1. アクセスを確認する

hogli devbox:doctor は読み取り専用です。プロンプトを表示したり、ホスト設定を変更したりすることはありません。 ボックスに接続するコマンドは、最初に同じ到達可能性チェックを実行するため、問題があれば先にここで解決してください。

• アクティブなテイルネットは posthog.com である必要があります。doctor はテイルネットを表示し、誤ったテイルネットが原因の場合はその旨を示します。
• PostHog の従業員は全員、テイルネットポリシーの group:employees を通じて Coder コントロールプレーンへの経路を持っています。アクセス権を得るための PR は不要です。
• doctor がコントロールプレーンに到達できないと報告した場合は、何かを変更する前に references/access-troubleshooting.md を読んでください。
• [missing] Commit signing agent は、ボックスの起動や使用を妨げません。ボックス上で署名付きコミットを行う場合にのみ関係します。

2. このマシンを一度セットアップする

hogli devbox:setup は対話型なので、ユーザー自身のターミナルで実行するよう依頼してください。 サーバーのバージョンに合わせた Coder CLI を ~/.hogli/bin にインストールし、ログインして、devbox:sync 用の固定バージョンの mutagen バイナリをインストールします。また、devbox:ssh と devbox:exec が使用する coder.* SSH ホストエントリーを書き込みます。 ~/.hogli/bin は PATH に含まれないため、手順で coder を直接使う必要がある場合は、その CLI を ~/.hogli/bin/coder として呼び出してください。 各オプション手順には --configure-<step> と --skip-configure-<step> フラグがあります。対象は ssh、git-identity、git-signing、region、dotfiles、claude です。 コマンドに Coder CLI vX does not match server vY と表示された場合は、もう一度実行してください。一致する CLI が再インストールされます。

Linux では、到達可能性チェックで sudo tailscale set --accept-routes が実行され、パスワードを求められることがあります。 エージェントが devbox コマンドを無人で実行する前に、セットアップを一度対話形式で実行してください。

3. ボックスを起動する

hogli devbox:start

初回はこれによってボックスが作成され、停止後は再開されます。 ボックスの起動スクリプトが完了すると処理が戻るため、その時点でボックスへの接続準備が整っています。devbox:restart、devbox:update、devbox:clone も同様に完了を待ちます。スクリプトが失敗した場合や待機がタイムアウトした場合でも、ボックスは動作し続け、hogli は hogli devbox:logs を案内する警告を表示します。 ワークスペースに --start-app が設定されている場合に限り、PostHog スタックが起動します。詳しくはPostHog アプリを実行するを参照してください。 --disk（100 または 200 GiB）が適用されるのは、ボックスの作成時のみです。 --region（us-east-1 または eu-central-1）を指定すると、そのリージョンのデフォルトボックスを起動し、存在しない場合は作成するため、既存のボックスを再開する場合は指定しないでください。 ボックスのリージョンは変更できません。

デフォルトのボックス名は devbox-<coder-user>、ラベル付きのボックス名は devbox-<coder-user>-<label> です。 eu-central-1 のボックスには -eu のサフィックスが付きます。たとえば devbox-<coder-user>-eu です。 正確な名前は hogli devbox:list で確認できます。 ラベル付きのボックスを対象にするには、ボックスを操作するコマンドで -n <label> を指定してください。

4. 接続する

ユーザーの要望に合わせて選択してください。

• シェル： hogli devbox:ssh。
• エディター： hogli devbox:open --vscode、--cursor、または --web。
• エージェントからのコマンド実行： hogli devbox:exec。詳しくはボックス上でコマンドを実行するを参照してください。
• ローカルで編集し、ボックス上で実行： hogli devbox:sync を使う前に references/sync.md を読んでください。
• 実行中のアプリ： PostHog アプリを実行するに従ってください。

5. 完了したら停止する

hogli devbox:stop はディスクを保持したまま、課金を停止します。 停止、起動、devbox:update では /home が保持されます。 hogli devbox:destroy は削除するため、ボックスにしかない、かけがえのないものは残さないでください。

ボックスでコマンドを実行する

hogli devbox:exec -- <command> は SSH 経由で単一のコマンドを実行し、その終了コードを返します。 コマンドは bash -lc '...' でラップしてください。 非ログインシェルではシェルのプロファイルが確実に読み込まれないため、~/.local/bin などログインシェルの PATH にあるツールは「command not found」と報告されます。 hogli のフラグとコマンド自体の間には -- を入れてください。 devbox:setup が SSH 設定を書き込むまで、devbox:exec と devbox:ssh は接続に失敗します。

PostHog アプリを実行する

変更の QA やリンクの共有など、ユーザーがアプリを必要としている場合にのみ、このセクションを使ってください。

スタックを起動する

• 新しいボックス： hogli devbox:start --start-app。この設定はワークスペースに保持されるため、以降の起動では毎回スタックがバックグラウンドで起動します。このフラグは hogli がボックスを作成するときにのみ適用されます。既存のボックスでは、Coder CLI がパラメーターの最後のビルド値を保持するため、hogli はフラグを拒否します。既存のボックスでは、Coder ダッシュボードのワークスペースのパラメーターから変更してください。
• 実行中のボックス： hogli devbox:exec -- bash -lc 'cd ~/posthog && ./bin/hogli up -d -y'。

起動を待つ

起動コマンドが戻った後も、スタックは起動を続けます。 200 または 302 が表示されるまで、上限を設けたループでポーリングしてください。 000 または 502 は、スタックがまだ起動中であることを示します。

hogli devbox:exec -- bash -lc "curl -s -o /dev/null -w '%{http_code}' --max-time 10 http://127.0.0.1:8010/"

既存のボックスで QA を再開するときは、同期を再作成したり、スタックを再起動したり、新しいボックスを作成したりする前に、状態を確認してください。

hogli devbox:status
hogli devbox:exec -- bash -lc 'cd ~/posthog && git status --short --branch && git rev-parse --short HEAD'
hogli devbox:sync --json

アプリが意図したブランチと SHA を提供し、対象のルートが読み込まれ、その API が動作していれば続行できます。 無関係なプロセスの状態が悪化していても、全体の健全性を追い求めるのではなく、そのことを記録してください。

ユーザーに URL を伝える

テンプレートはアプリを Coder のサブドメインアプリとして公開しており、開けるのはボックスの所有者だけです。

https://app--<workspace>--<coder-user>.<coder-host>

<coder-host> は hogli devbox:doctor の Coder URL のホストで、hogli devbox:list にはワークスペース名が表示されます。 たとえば、coder.dev.posthog.dev 上の jane-d が所有する devbox-jane-d は、https://app--devbox-jane-d--jane-d.coder.dev.posthog.dev です。 ユーザーは tailnet に接続している必要があり、ブラウザーでは最初に Coder へのサインインが必要です。

リンクを渡す前に確認してください。 Coder はアプリに対してテンプレートのヘルスチェックを実行するため、ユーザーのセッショントークンを使ってリクエストを送るのではなく、そのステータスを確認してください。

~/.hogli/bin/coder list --output json | jq -r '.[] | select(.name=="<workspace>") | .latest_build.resources[]?.agents[]?.apps[]? | select(.slug=="app") | .health'

healthy は、Coder が URL を正常に動作しているアプリにルーティングしていることを意味します。 initializing はチェックがまだ成功していないことを、unhealthy はチェックが繰り返し失敗していることを意味します。

ユーザーが localhost を使いたい場合は、代わりに hogli devbox:forward を使います。 ボックスのポート 8010 を localhost:8010 にトンネルし、停止するまでターミナルを占有します。 ローカルのスタックがすでに 8010 を使っている場合は、--port 8011 を指定してください。

その他のタスク

• ボックス上のトークン： Coder ユーザーシークレットとして保存すると、そのユーザーが所有するすべてのボックスに届きます。hogli devbox:secret:set GH_TOKEN は、非表示のプロンプトまたは --file から値を読み込みます。トークンをコマンドラインや会話に決して記載しないでください。シークレットが届くのは設定後に起動したボックスのみなので、実行中のボックスでは hogli devbox:restart を実行してください。テンプレートには CLAUDE_CODE_OAUTH_TOKEN、GH_TOKEN、ANTHROPIC_API_KEY、OPENAI_API_KEY、POSTHOG_GIT_SIGNING_KEY が記載されており、hogli devbox:setup --configure-git-signing によって POSTHOG_GIT_SIGNING_KEY が設定されます。devbox:secret:list には名前、環境変数、説明が表示されますが、値は表示されません。
• 同じ状態の 2 つ目のボックス： hogli devbox:clone --as <label> は、実行中のボックスのディスク全体（ボックス上のシークレットも含む）を、ソースボックスと同じリージョンにある devbox-<coder-user>-<label> にコピーします。一貫性のあるコピーを作成するには、先にソース上のスタックを停止してください。確認を求められるため、ユーザーの同意を得てから -y を渡してください。ボックスをクローンできるのは所有者のみです。
• テンプレートの更新： ボックスが古い場合、hogli devbox:update で最新のテンプレートを適用できます。devbox:start も、古いボックスを起動するときに更新します。devbox:start と devbox:clone が作成するボックスでは Coder の自動更新が有効になっているため、Web UI または自動起動から起動するとき、および hogli devbox:restart の実行時にも最新のテンプレートに更新されます。Coder はボックスの実行中に更新することはありませんが、古いボックスを再起動するとテンプレート全体が更新され、devbox:update が警告する一度限りの依存関係の再インストールが発生することがあります。
• ディスクの空き容量がない： hogli devbox:cleanup:disk -n <label> は、ラベルが付いたボックスをクリーンアップします。ワークスペースを指定しない場合はこのマシンをクリーンアップします。デフォルトのボックスにはラベルがないため、次のコマンドでクリーンアップしてください：hogli devbox:exec -- bash -lc 'cd ~/posthog && ./bin/hogli devbox:cleanup:disk'。--docker を指定すると、停止中のコンテナも削除します。--cargo を指定すると、Rust のビルド出力も削除されるため、全体を再ビルドする必要があります。
• ペアリング： hogli devbox:share --user <coder-user> --role use でアクセス権を付与し、devbox:users でユーザー名を一覧表示できます。devbox:unshare でアクセス権を削除した後は、hogli devbox:restart を実行してください。
• ビルドとエージェントのログ： hogli devbox:logs -f。
• 個人用セットアップ： ボックスは出荷時の状態ですぐに使えます。ボックス上で行った変更は、停止や更新の後も保持されます。hogli devbox:setup --configure-dotfiles を実行すると、ボックスが起動時に適用する dotfiles リポジトリが保存され、その実行可能な install.sh が実行されます。保存したリポジトリの URL は、hogli が作成するボックスに適用されます。既存のボックスで変更するには、Coder ダッシュボードでワークスペースのパラメーターを編集してください。

注意点

• シークレットの値をトランスクリプト、ログ、PR、コマンドラインに出力しないでください。
• code-server（devbox:open --web）では SSH エージェント転送を利用できないため、そこでのコミット署名は失敗します。コミットに署名するには、SSH 経由で VS Code Desktop、Cursor、または JetBrains を使用してください。