https://github.com/lucabello/docker-captain
⚓ A friendly CLI to manage multiple Docker Compose deployments with style — powered by Typer, Rich, questionary, and sh.
https://github.com/lucabello/docker-captain
cli docker docker-compose
Last synced: about 2 months ago
JSON representation
⚓ A friendly CLI to manage multiple Docker Compose deployments with style — powered by Typer, Rich, questionary, and sh.
- Host: GitHub
- URL: https://github.com/lucabello/docker-captain
- Owner: lucabello
- License: apache-2.0
- Created: 2025-10-11T07:37:11.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2025-12-17T13:40:21.000Z (3 months ago)
- Last Synced: 2025-12-18T21:58:15.769Z (3 months ago)
- Topics: cli, docker, docker-compose
- Language: Python
- Homepage:
- Size: 120 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yaml
- License: LICENSE
Awesome Lists containing this project
- fucking-awesome-docker - docker-captain - A friendly CLI to manage multiple Docker Compose deployments with style — powered by Typer, Rich, questionary, and sh. (Container Operations / User Interface)
- awesome-docker - docker-captain - A friendly CLI to manage multiple Docker Compose deployments with style — powered by Typer, Rich, questionary, and sh. (Container Operations / User Interface)
README
# ⚓ docker-captain
[](https://pypi.org/project/docker-captain/)
[](https://github.com/lucabello/docker-captain/releases)
[](https://github.com/lucabello/docker-captain/actions/workflows/publish.yaml)
**docker-captain** is a friendly command-line tool that helps you manage multiple Docker Compose projects under a single folder.
---
## 🚀 Features
For a quick overview of the available commands, run `docker-captain --help`.
### 🔍 Project Auto-Detection
`docker-captain` automatically detects any subfolder containing a Docker Compose file — such as `compose.yaml`, `compose.yml`, `docker-compose.yaml`, or `docker-compose.yml`.
It scans the folder specified in the configuration file, or passed in the `DOCKER_CAPTAIN_PROJECTS` environment variable, which you can export here:
```bash
export DOCKER_CAPTAIN_PROJECTS=/path/to/your/deployments # takes precedence over the config file
```
Detection is purely based on the file names — if a folder contains one of those Compose files, it’s recognized as a valid “project”, taking its name from the folder.
### ⚙️ Project Management via `manage`
Use the `docker-captain manage` command to interactively select which projects should be considered *active*.
You’ll see a multi-select list of all detected projects — you can check or uncheck them using the keyboard, then confirm with Enter.
The selected projects become your *active fleet*, used by commands like `rally` and `abandon`.
### 🚢 Easy Interaction with Single Projects
Need to start or stop one project?
Use these straightforward commands:
```bash
docker-captain start calibre --detach --remove-orphans
docker-captain stop calibre --remove-orphans
docker-captain restart calibre
```
They’re thin wrappers around standard `docker compose` commands (`up`, `down`, and `restart`), but automatically use the correct compose file and folder context.
Flags:
* `-d` / `--detach`: Run containers in background.
* `--remove-orphans`: Remove orphaned containers not defined in the compose file.
### 📋 Listing Projects with `list`
See all detected projects neatly formatted in a Rich table:
```bash
docker-captain list
```
This shows:
* **Project** name
* Whether it’s **Active** (selected via `manage`)
* Whether it’s currently **Running** (`docker compose ls` is checked behind the scenes)
You can also view the compose file paths with `--verbose`:
```bash
docker-captain list --verbose
```
### ⚓ Rally and Abandon Your Fleet
Once you’ve marked projects as *active* using `manage`, you can control them all together:
* **Start all active projects:**
```bash
docker-captain rally --detach
```
* **Stop all active projects:**
```bash
docker-captain abandon
```
These commands behave like `start` and `stop`, but apply to every active project in one go — perfect for booting up or shutting down your entire environment.
---
## 📦 Installation
You can install `docker-captain` using `uv`, `pipx`, or plain `pip`.
```bash
# Install with
uv tool install docker-captain
pipx install docker-captain
# or try it out with
uvx docker-captain
```
---
## 🗒️ Configuration
`captain-docker` support a simple YAML config file with the following structure:
```yaml
# ~/.config/docker-captain/config.yaml (on Linux)
projects_folder: /path/to/your/deployments # environment variable: DOCKER_CAPTAIN_PROJECTS_FOLDER
```
This configuration file can be generated interactively by running `captain-docker configure`.
---
## 🧭 Folder Structure Example
Your deployments might look like this:
```
~/Deployments/
├── calibre/
│ └── compose.yaml
├── immich/
│ ├── compose.yaml
│ └── immich.env
├── paperless-ngx/
│ ├── compose.yaml
│ └── paperless-ngx.env
└── syncthing/
└── compose.yaml
```
Each subfolder is automatically detected as a project if it has a Compose file.
---
## 🧠 Tech Stack
| Library | Purpose |
| -------------------------------------------------- | ---------------------------- |
| [Typer](https://typer.tiangolo.com/) | CLI framework |
| [Rich](https://rich.readthedocs.io/) | Beautiful terminal output |
| [Questionary](https://github.com/tmbo/questionary) | Interactive prompts |
| [sh](https://amoffat.github.io/sh/) | Simple subprocess management |
| [PyYAML](https://pyyaml.org/) | YAML parsing |
---
## 🐙 Example Workflow
```bash
# Detect and list all projects
docker-captain list
# Choose which projects are active
docker-captain manage
# Start all active projects
docker-captain rally -d
```
---
## 💡 Inspiration
I've been using `docker-compose.yaml` files to manage my home server for a while.
I found the internet is full of tools to observe docker deployments, but I couldn't find one to manage my Docker Compose files.
I wanted something simple, lightweight, and portable.
I stumbled across [jenssegers/captain](https://github.com/jenssegers/captain/), a Go project with a similar idea - a simple wrapper around `docker compose`, but only acting on one project at a time.
Given Python is my main language and the project hasn't seen any activity in 3 years, I decided to extend its scope and write `docker-captain`.
Hope this is useful to someone, happy sailing! ⛵
---
## 🔧 Development
If you want to contribute to the project, please start by opening an [issue](https://github.com/lucabello/docker-captain/issues).
You can interact with the project via `uv` and the `justfile` (from [casey/just](https://github.com/casey/just)) at the root of the repository.
Simply run `just` to show the available recipes.
```bash
# Create a virtual environment for the project
uv venv --all-groups
source .venv/bin/activate
# Linting, formatting, etc.
just # show the list of all commands
just lint
# Run docker-captain from the local folder
uv run docker-captain
```