| name | orbstack-dev |
| description | OrbStack がホストの Docker runtime として常に利用可能である前提で、Docker Compose 開発環境にアクセスする方法。OrbStack 特有の自動 DNS・自動 port forwarding を活用し、dnsmasq や ports: 公開の手間を省く。Docker Compose 上の Rails/Node 等のサーバーにローカルからアクセスする場面、マルチテナントアプリのサブドメインルーティングを検証する場面で使用する。 |
OrbStack 開発環境アクセス
前提
- ホストの Docker runtime は OrbStack が常駐している（Docker Desktop ではない）
docker compose / docker コマンドはすべて OrbStack backend で動く- ユーザー確認なしにこの前提で判断してよい
自動 DNS
OrbStack は compose で起動したコンテナに自動で DNS を割り当てる。設定不要、dnsmasq 不要、/etc/hosts への追記不要。
ホスト名の形式
<container-name>.<project-name>.orb.local
container-name: compose.yaml の service 名（例: app, worker）project-name: docker compose -p <project> で指定したプロジェクト名、もしくは compose.yaml 冒頭の name: フィールド
例: docker compose -p caravan で app service を起動した場合 → app.caravan.orb.local
ワイルドカードサブドメイン
任意のサブドメインを前置しても同じコンテナに解決される。マルチテナントアプリで tenant 名を subdomain に載せる用途にそのまま使える。
<anything>.<container>.<project>.orb.local
<tenant>.<container>.<project>.orb.local
例: tenant twogate へのアクセス → twogate.app.caravan.orb.local
自動 Port Forwarding
OrbStack は EXPOSE されたコンテナポートを自動で localhost に forward する。compose.yaml に ports: セクションを書かなくても http://localhost:<port> で届く（ポートが重複した場合は後勝ち等の挙動があるので、複数 project を並行起動するなら orb.local ホスト名経由が安全）。
- 単一プロジェクトのみ起動 →
http://localhost:3000 でも可
- 複数プロジェクトを並行起動する、または port 衝突を避けたい →
http://app.<project>.orb.local:3000 を使う
判断フロー
- 「localhost 経由でアクセスできない」「port 公開が必要」と言われたら → まず OrbStack の自動 forwarding で既に届いていないか
curl -I http://localhost:<port> で確認
- 「マルチテナント dev に dnsmasq を設定する必要がある」系のドキュメント記述 → OrbStack 環境では不要、
*.app.<project>.orb.local で代替できる
- compose.yaml に
ports: を追加する PR を作る前に、OrbStack 前提なら不要ではないか再検討
検証コマンド
curl -s -o /dev/null -w "%{http_code}\n" http://<container>.<project>.orb.local:<port>
curl -s -o /dev/null -w "%{http_code}\n" http://<tenant>.<container>.<project>.orb.local:<port>
注意点
- OrbStack の DNS は OrbStack が起動している間のみ有効。CI 等 OrbStack がない環境では
*.orb.local は解決されない。CI 用設定をこの機能に依存させない。
- プロジェクト名にアンダースコア等の DNS 非互換文字を使うと解決されない。ハイフン or 英数字で統一する。
- compose の
name: フィールドと -p フラグが両方ある場合、-p が優先される。
