Zenn
🐳

Docker Composeのポート衝突を自動解決するgoposeを作った話

に公開
Docker
Go
gopose
tech

忙しい人へのまとめ

  • gopose は Docker Compose のポートバインディング衝突を自動で検出し解決する CLI ツールです
  • docker-compose.yml を直接書き換えず docker-compose.override.yml を生成して衝突を回避します
  • 並列処理による高速スキャンや詳細ログ出力など便利機能が盛りだくさん
  • AI と連携して並列開発を行う際 (git worktree 等) のポート衝突をスマートに回避できます

goposeの特徴

  • ✅ 非破壊的: 元の docker-compose.yml を変更しません
  • ✅ 自動検出: システムの使用中ポートをチェック
  • ✅ 自動解決: 空きポートを自動で割り当て
  • ✅ 構造化ログ: 豊富なログ出力でデバッグが楽
  • ✅ 並列処理: スキャンを高速化

どうして作ったの？

ローカル開発では Docker 上で複数のブランチを同時に試すことがよくあります。AI にコード生成を任せながら git worktree で並行作業していると、同じポートを使うサービスが衝突してしまいがちです。毎回 compose ファイルを直すのは面倒なので、ポートを自動で振り替えてくれる gopose を作りました。
特にマイクロサービスをいくつも立ち上げるとポートの重複を毎回手で直すのは骨が折れます。gopose なら差分用の override.yml を勝手に書き出してくれるので、元の compose ファイルを汚さずに済みます。AI とのペアプロやブランチ毎の実験でも安心です。

実行するとどうなる？

gopose up を走らせると、Docker Compose ファイルを解析して空いているポートへ自動で割り当て直します。出力例は次のようになります。

gopose up
ポート衝突解決を開始
Docker Composeファイル検出開始
Docker Composeファイル発見
Docker Composeファイル検出完了
Docker Composeファイルを自動検出
Docker Composeファイル解析開始
Docker Composeバージョンが指定されていません
Docker Composeファイル解析完了
ポート衝突検出開始
netstatを使用してポートスキャンを開始
ポートスキャン完了
システムポート衝突検出
ポート衝突検出完了
ポート衝突検出完了
ポート衝突解決開始
netstatを使用してポートスキャンを開始
ポートスキャン完了
範囲内ポートフィルタリング完了
ポート割り当て成功
解決案最適化開始
解決案最適化完了
ポート衝突解決完了
ポート解決
Override生成開始
ポートマッピング更新
Override生成完了
Override検証開始
Overrideのバージョンが指定されていませんが、Docker Composeの最新バージョンでは非推奨のため許可します
Override検証完了
Overrideファイル書き込み開始
Overrideファイル書き込み完了
Override.ymlファイルが生成されました
既存のコンテナを停止してからDocker Composeを起動
[+] Running 2/2
 ✔ Container gopose-web-1  Removed                                                                                         0.0s
 ✔ Network gopose_default  Removed                                                                                         0.2s
Docker Composeを起動
Docker Composeを実行
[+] Running 2/2
 ✔ Network gopose_default  Created                                                                                         0.0s
 ✔ Container gopose-web-1  Created                                                                                         0.0s
Attaching to web-1

インストール

Go が入っていれば go install 一発で導入できます。

go install github.com/harakeishi/gopose@latest

基本的な使い方

gopose up を実行すると、ポート衝突を検出して利用可能なポートへ自動で割り当てます。

gopose up

初回実行時に"override.ymlを生成しました"と表示されれば成功です。ポート番号は自動的に振り直され、Docker Composeが起動します。

生成された docker-compose.override.yml ファイルを削除したい場合は手動で削除してください。

もう少し便利に

特定の docker-compose ファイルを指定したり、割り当てるポート範囲を変えたりといった柔軟なオプションも用意しています。

# 例: ポート範囲を指定して実行
gopose up --port-range 9000-9999

# 例: 特定のcomposeファイルを指定
gopose up -f custom-compose.yml

# 例: ドライランで実行内容を確認
gopose up --dry-run

除外設定や詳細なログ出力もできるので、気になる方は gopose up --help を眺めてみてください。

終わりに

ポート衝突で開発が止まるストレスを少しでも減らしたくて gopose を公開しました。興味のある方は harakeishi/gopose を覗いてみてください。フィードバックやプルリクエストも大歓迎です！

Discussion