worktree 対応の Docker Compose は固定 container_name と固定ポートを避ける
Docker
開発環境
設計判断
Git worktree や複数 checkout から同じ Compose 定義を起動する前提では、container_name と固定ホストポートが衝突原因になりやすい。
判断基準:
- 複数 worktree を同時に起動したいなら、
container_nameは基本的に指定しない。Compose の project name による自動命名に任せると、worktree ごとにコンテナ名・ネットワーク名・ボリューム名を分離できる。 - ホストから DB や API に接続する必要がある場合、固定の
5432:5432や8080:8080は 2 つ目の worktree で失敗する。${DB_PORT:-5432}:5432のようにホスト側ポートを環境変数化するか、共有 DB を 1 つだけ起動する設計にする。 - 逆に、全 worktree で 1 つの共有 DB を使う設計なら、
COMPOSE_PROJECT_NAMEを明示して「常に同じ Compose project を操作する」ことをドキュメント化する。中途半端に project name だけ分かれてコンテナ名だけ固定すると、別 worktree からcompose upしたときに既存コンテナ名と衝突する。
検証方法: 新しい worktree/checkhout を 2 つ作り、両方で docker compose up -d 相当を実行する。2 つ目で container name conflict や port is already allocated が出るなら worktree 対応として不十分。共有 DB 方針の場合は、2 つ目の checkout から同じ Compose project の既存 DB を再利用できることを確認する。