Installation and Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• install.sh
• Formula/docktree.rb
• CONTRIBUTING.md
• internal/cli/init.go
• internal/cli/up.go
• internal/config/config.go

Docktree is a Go-based CLI tool designed to facilitate isolated Docker Compose environments across multiple git worktrees. The installation process provides several methods ranging from automated shell scripts and package managers to building from source, while the setup process focuses on initializing project-specific configurations to manage port allocation and shared services.

The primary goal of the installation and setup phase is to establish a environment where docktree can intercept Docker Compose calls to apply unique project names, container names, and port mappings, ensuring that different git worktrees do not collide on host resources.
Sources: README.md:1-13, CONTRIBUTING.md:44-50

Installation Methods

1. Automated Shell Script

The quickest way to install Docktree on macOS or Linux is via the official installer script. This script automatically detects the system architecture (amd64 or arm64) and operating system (linux or darwin), fetches the latest release from GitHub, verifies checksums, and installs the binary to a specified directory.

# Default installation
curl -fsSL https://raw.githubusercontent.com/Bnjoroge1/docktree/main/install.sh | sh

# Installation with overrides
VERSION=v0.1.0 INSTALL_DIR=~/.local/bin curl -fsSL https://raw.githubusercontent.com/Bnjoroge1/docktree/main/install.sh | sh

Sources: README.md:18-20, install.sh:31-61, install.sh:109-122

2. Homebrew (macOS)

For macOS users, a Homebrew formula is provided. This method manages dependencies and handles binary linking automatically.

brew tap Bnjoroge1/tap
brew trust Bnjoroge1/tap   # Required for Homebrew 4.4+
brew install docktree

Sources: README.md:23-26, Formula/docktree.rb:1-33

3. Build from Source

Developers or users on other platforms can install Docktree using the Go toolchain. This requires Go 1.25 or higher.

go install github.com/bnjoroge/docktree/cmd/docktree@latest

Sources: README.md:29-30, CONTRIBUTING.md:46

Installation Flow Logic

The following diagram illustrates the internal logic of the install.sh script during the installation process.

The script uses uname -s and uname -m to determine the platform and curl or wget for downloads.
Sources: install.sh:31-72, install.sh:109-166

---

Project Initialization

Once the binary is installed, the project must be initialized to use Docktree effectively. This is handled by the docktree init command, which scans the repository for existing Docker Compose files and proposes a docktree.yml configuration.

The docktree init Process

The initialization command performs a comprehensive scan of the local environment:

• Compose Detection: Finds all docker-compose.yml or compose.yml files.
• Service Analysis: Detects "shareable" services such as databases (Postgres, MySQL, MongoDB) or caches (Redis).
• Environment Mapping: Identifies .env files and environment variables that likely contain connection strings (e.g., DATABASE_URL).
• Dependency Scanning: Warns if services use secret wrappers like Infisical or Doppler, which might hide environment variables from Docktree's rewriting logic.

Sources: internal/cli/init.go:68-105, internal/cli/init.go:343-366

Initialization Outcomes

Flag	Behavior
(default)	Writes a docktree.yml.proposed file for manual review.
--dry-run	Outputs the proposed YAML configuration directly to stdout.
--force	Overwrites any existing docktree.yml with detected defaults.
--apply	Reads user decisions (from stdin as JSON) to generate the final config.

Sources: internal/cli/init.go:121-155, internal/cli/init.go:401-412

---

Configuration (docktree.yml)

The docktree.yml file is the source of truth for how Docktree manages a repository. It defines which files to include, how to handle local setup, and rules for port/volume sharing.

Configuration Schema

compose:
  files:
    - docker-compose.yml # List of compose files to merge

setup:
  copy:
    - .env               # Files to copy from main repo to worktrees
  symlink:
    - node_modules       # Directories to symlink
  run:
    - npm install        # Commands to run in new worktrees

ports:
  bind_host: "127.0.0.1"
  range: "41000-49999"   # Range for auto-allocated ports

shared:
  services:
    db:
      kind: postgres
      tenancy: per_database # Isolated DBs on a shared instance

Sources: README.md:68-87, internal/config/config.go:15-60

Port Allocation Logic

When a user runs docktree up, the system performs the following sequence to ensure isolation:

The CLI generates a temporary override file that maps the original container ports to the newly allocated host ports.
Sources: internal/cli/up.go:183-220, README.md:43-51

---

Workspace Setup for Development

For developers contributing to Docktree, the environment setup involves the Go toolchain and a task runner called just.

Prerequisites

• Go: Version pinned in go.mod (currently Go 1.25).
• Docker: Must include the compose plugin.
• just: (Optional) Used for running project tasks.

Build Commands

Task	Command	Description
Build	just build	Compiles the binary to ./docktree.
Install	just install	Builds and installs to $GOPATH/bin.
Test	just test-all	Runs the full suite including integration tests.

Sources: CONTRIBUTING.md:44-67

Conclusion

Installation of Docktree is designed to be platform-agnostic, supporting major Unix-like systems through shell scripts and Homebrew. Setup is largely automated via the init command, which abstracts the complexity of mapping Docker Compose services to isolated worktree environments. By defining project boundaries in docktree.yml, users can ensure seamless execution of concurrent stacks without manual port management.