Worktree Manager

Manage Docker-based dev instances and git worktrees. Handles app container lifecycle, database seeding, and proxy route activation. Requires mysql-manager and proxy-manager to be running first.

Manages Docker app instances and git worktrees for local development.

Each instance gets its own docker-compose stack (backend + frontend), isolated git branch, and .env.worktree-<name> file. MySQL and nginx-proxy are managed separately by their own plugins.

Prerequisites

Start these first (order matters):

1. proxy-manager start — creates the shared Docker network (nginx-proxy_net)
2. mysql-manager start — starts the shared MySQL container

Architecture

project/
├── docker-compose.yml        # app stack template (backend + frontend)
├── run.sh                    # this plugin's entry point (copy to project root)
├── .env.base                 # main instance env
├── .env.worktree-<name>      # per-worktree env (gitignored)
└── .worktrees/
    └── <name>/               # git worktree (gitignored)

• main → .env.base, project root
• worktree → .env.worktree-<name>, checked out at .worktrees/<name>
• URLs: http://<name>.frontend.localhost / http://<name>.backend.localhost

Commands

All commands run from the project root:

./run.sh list                        # show all instances + mysql/proxy status
./run.sh start [main|<name>]         # seed db, start containers, connect proxy
./run.sh stop  [main|<name>]         # stop containers (db persists)
./run.sh restart [main|<name>]       # stop then start
./run.sh logs  [main|<name>]         # follow container logs
./run.sh create-worktree <name>      # git worktree + branch + env file
./run.sh remove-worktree <name>      # stop containers + drop db + remove worktree

How to Execute Tasks

Full environment setup (first time)

proxy-manager/run.sh start        # network + nginx-proxy
mysql-manager/run.sh start        # MySQL
./run.sh start main               # main app instance

Create a new worktree and start it

1. ./run.sh create-worktree <name> — creates branch worktree/<name>, dir .worktrees/<name>, env file
2. ./run.sh start <name> — seeds db from main snapshot, starts containers, activates proxy route
3. URLs reported at the end

Stop an instance

./run.sh stop <name>

Remove a worktree (destructive — always confirm first)

Confirm with user: "Remove worktree '<name>'? Deletes containers, database, git worktree (branch worktree/<name>), and .env.worktree-<name>."

./run.sh remove-worktree <name>

List all instances

./run.sh list

What start Does

1. Checks MySQL container is running (exits with error if not)
2. CREATE DATABASE IF NOT EXISTS for the instance
3. For non-main instances: dumps codai_main → instance db
4. docker compose up --build -d
5. docker network connect — proxy to instance network (activates routes)

Rules

• Always check ./run.sh list before starting — it shows MySQL/proxy status.
• Always confirm before remove-worktree — it is irreversible.
• After start, print the frontend and backend URLs.
• If ./run.sh is not executable: chmod +x run.sh
• .env.worktree-* files and .worktrees/ dir must be gitignored.

Configuration

Variable	Default	Purpose
MYSQL_CONTAINER	codai_db	MySQL container name
MYSQL_ROOT_PASS	secret	MySQL root password
MYSQL_MAIN_DB	codai_main	Source DB for snapshots
PROXY_CONTAINER	codai_nginx_proxy	nginx-proxy container name
PROJECT_PREFIX	codai-dev	Docker Compose project prefix

Related Plugins

• proxy-manager — nginx-proxy lifecycle and network management (start first)
• mysql-manager — MySQL lifecycle and database admin (start second)