同一プロジェクトのdockerを複数立ち上げたときにポート衝突が面倒だった

LLMでworktreeで並列で実装させるときに、APIとか立ち上げるとポート衝突が発生します。

GitHub - mocyuto/zgt: A simple CLI tool for parallel git worktree development を作ったのも、それが一つの動機です。 （長くて打つのが面倒なのと、git サブコマンドだと補完が効かないので git-wt から zgt にrename しました）

最近はみんながどんどんツール作るけど、各ツールに自分のワークフローをあわせるより自分好みのツールをLLMで作ったほうが早いなと思って作ったというのが経緯です。

今回は拙作のzgt を使って、worktree間でのポート衝突を避けて動かす方法を紹介します。

yuutookun.hatenablog.com

手順

1. zgt.config.yaml の作成

プロジェクトのrootに zgt.config.ymlを置きます

zgt init
zgt config edit

# zgt.config.yaml
ports:
  api: 8080  # API サーバーのベースポート
  web: 3000  # フロントエンドのベースポート

env:
  # Docker Compose のプロジェクト名をワークツリーごとにユニークにする
  COMPOSE_PROJECT_NAME: "git-wt-{{.Repo}}-{{.Branch}}"

hooks:
  add:
    # 依存関係のインストールも自動化
    - "cd {{.Path}} && npm install"
  rm:
    # worktreeを削除したときにmainブランチをpullして最新にする
    - git pull origin main:main 

tmux: # worktreeを作成した際に自動で立ち上げるtmux
    enabled: true
    windowname: ""
    panes:
        - id: main
          target: ""
          commands:
            - opencode
          split: ""
          size: ""
        - id: side
          target: main
          commands:
            - direnv allow .
            - cd server
            - direnv allow .
            - eval $(zgt env) # これでAPI_PORT, COMPOSE_PROJECT_NAMEがexportされる
            - uv sync
          split: horizontal
          size: 50%
        - id: ""
          target: side
          commands:
            - direnv allow .
            - cd front
            - eval $(zgt env)
            - yarn
          split: vertical
          size: ""
        - id: ""
          target: main
          commands:
            - ls
          split: vertical
          size: 20%

ports: ここに定義したポート番号に zgt がワークツリーごとに自動でインデックス（0, 1, 2...）を加算した値を割り当ててくれます。

COMPOSE_PROJECT_NAME: これをワークツリーごとに変えることで、Docker コンテナ名が衝突するのを防ぎます。 *1

hooks: ワークツリー作成後のディレクトリ移動や初期セットアップも自動化できます。

tmux: tmux設定で、新しいワークツリー用のウィンドウを即座に開くことができ、非常に快適です。

2. compose.ymlの修正

# docker-compose.yml
services:
  api:
    build: ./api
    environment:
        DBHOST: main-db-1 # docker container name
        # DBHOST:db 
    ports:
      - "${API_PORT:-8080}:8080" # ホスト側のポートを環境変数で動的に変更

  db:
    image:  postgres:15
    ports:
      - "${DB_PORT:-5432}:5432"

networks:
  shared-db-network:
    name: common-db-net # 固定のネットワーク名。external指定なしでも共有可能

複数worktreeで共有するなら一度だけ docker compose up db -d

3. ワークツリー作成

準備ができたら、新しいワークツリーを追加して起動します。

# 1. 新しいワークツリーを追加
zgt add feature-a
# 2. 自動で tmux ウィンドウが開き、evalで環境変数がセットされ、npm install なども走る（hooksやtmuxの設定による）
# 3. Docker Compose 起動
docker compose up api  # 指定したポートでAPIが起動

まとめ

ポート管理は結構面倒なので、マルチワークツリー開発をより快適にするために、ぜひ mocyuto/zgt を使ってみてください。