gopose

Automatically detect and resolve Docker Compose port & network conflicts.

The Problem

When running multiple Docker Compose projects, port conflicts are inevitable. You either manually hunt for available ports or wade through cryptic error messages.

gopose fixes this automatically. It scans for conflicts and generates a compose.override.yml with safe port assignments — without touching your original compose.yml.

$ gopose up

  SERVICE   ORIGINAL   RESOLVED   REASON
  web       3000       8001       port in use
  api       5432       8002       port in use

  NETWORK   ORIGINAL         RESOLVED
  default   172.20.0.0/24    10.20.0.0/24

Override file generated: compose.override.yml
Run `docker compose up` to start services.

Quick Start

go install github.com/harakeishi/gopose@latest

cd your-compose-project/
gopose up

That's it. gopose detects conflicts, generates the override, and you run docker compose up as usual.

Installation

Go Install

go install github.com/harakeishi/gopose@latest

Binary Releases

Download from GitHub Releases:

# macOS (arm64)
curl -L https://github.com/harakeishi/gopose/releases/latest/download/gopose_darwin_arm64.tar.gz | tar xz
sudo mv gopose /usr/local/bin/

# Linux (amd64)
curl -L https://github.com/harakeishi/gopose/releases/latest/download/gopose_linux_amd64.tar.gz | tar xz
sudo mv gopose /usr/local/bin/

# Windows (amd64)
curl -L https://github.com/harakeishi/gopose/releases/latest/download/gopose_windows_amd64.zip -o gopose.zip
unzip gopose.zip

Build from Source

git clone https://github.com/harakeishi/gopose.git
cd gopose
make build
sudo make install

Usage

Commands

Command	Description
gopose up	Detect conflicts and generate compose.override.yml
gopose up --dry-run	Preview changes without generating files
gopose status	Show current conflict status
gopose version	Print version

Common Options

Option	Description	Example
-f	Specify compose file	gopose up -f custom-compose.yml
--port-range	Set port allocation range	gopose up --port-range 9000-9999
--dry-run	Preview without changes	gopose up --dry-run
--verbose	Enable verbose logging	gopose up --verbose
--detail	Show timestamps and fields	gopose up --detail

Configuration

Create a .gopose.yaml in your project or home directory:

port:
  range:
    start: 8000
    end: 9999
  reserved: [8080, 8443]  # Never assigned, even if available

resolver:
  strategy: "minimal_change"

See Configuration Reference for all options.

Features

• Non-destructive — Never modifies your original compose.yml
• Port conflict resolution — Detects system port conflicts and assigns available ports
• Network conflict resolution — Detects Docker network subnet conflicts and assigns safe alternatives (details)
• Reserved ports — Exclude specific ports from allocation (details)
• Cross-platform — Linux, macOS, and Windows

Platform Test Status

Platform	Test Status
macOS	Tested
Linux	Tested
Windows	Not tested

Documentation

Document	Description
Configuration Reference	Full .gopose.yaml options
Reserved Ports	Port reservation behavior and examples
Network Conflict Avoidance	Subnet conflict resolution details

Contributing

git clone https://github.com/harakeishi/gopose.git
cd gopose
make deps    # Install dependencies
make test    # Run tests
make check   # Lint + vet + test

License

MIT License

Contributors

Thanks goes to these wonderful people (emoji key):

doskoi 💻

Kosuke Nakamura 💻

Akinori Takigawa 💻

aaaaninja 💻

---

Developed by harakeishi

Bug Reports · Discussions · Wiki