{"id":32352271,"url":"https://github.com/lucabello/docker-captain","last_synced_at":"2026-01-14T07:54:50.323Z","repository":{"id":321202483,"uuid":"1074127141","full_name":"lucabello/docker-captain","owner":"lucabello","description":"⚓ A friendly CLI to manage multiple Docker Compose deployments with style — powered by Typer, Rich, questionary, and sh.","archived":false,"fork":false,"pushed_at":"2025-12-17T13:40:21.000Z","size":123,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-18T21:58:15.769Z","etag":null,"topics":["cli","docker","docker-compose"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lucabello.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yaml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":"lucabello"}},"created_at":"2025-10-11T07:37:11.000Z","updated_at":"2025-12-17T13:40:24.000Z","dependencies_parsed_at":"2025-10-28T12:23:27.228Z","dependency_job_id":"0d8fb493-e97d-43a6-ba21-4e1a038ef1b8","html_url":"https://github.com/lucabello/docker-captain","commit_stats":null,"previous_names":["lucabello/docker-captain"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/lucabello/docker-captain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucabello%2Fdocker-captain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucabello%2Fdocker-captain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucabello%2Fdocker-captain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucabello%2Fdocker-captain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucabello","download_url":"https://codeload.github.com/lucabello/docker-captain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucabello%2Fdocker-captain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28413527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","docker","docker-compose"],"created_at":"2025-10-24T10:01:00.677Z","updated_at":"2026-01-14T07:54:50.317Z","avatar_url":"https://github.com/lucabello.png","language":"Python","funding_links":["https://ko-fi.com/lucabello"],"categories":["User Interfaces"],"sub_categories":["Terminal"],"readme":"# ⚓ docker-captain\n\n[![PyPi Release](https://img.shields.io/pypi/v/docker-captain?label=PyPi\u0026color=blue)](https://pypi.org/project/docker-captain/)\n[![GitHub Release](https://img.shields.io/github/v/release/lucabello/docker-captain?label=GitHub\u0026color=blue)](https://github.com/lucabello/docker-captain/releases)\n[![Publish to PyPi](https://github.com/lucabello/docker-captain/actions/workflows/publish.yaml/badge.svg)](https://github.com/lucabello/docker-captain/actions/workflows/publish.yaml)\n![Commits Since Release](https://img.shields.io/github/commits-since/lucabello/docker-captain/latest?label=Commits%20since%20last%20release\u0026color=darkgreen)\n\n\n**docker-captain** is a friendly command-line tool that helps you manage multiple Docker Compose projects under a single folder.\n\n---\n\n## 🚀 Features\n\nFor a quick overview of the available commands, run `docker-captain --help`.\n\n### 🔍 Project Auto-Detection\n`docker-captain` automatically detects any subfolder containing a Docker Compose file — such as `compose.yaml`, `compose.yml`, `docker-compose.yaml`, or `docker-compose.yml`.  \nIt scans the folder specified in the configuration file, or passed in the `DOCKER_CAPTAIN_PROJECTS` environment variable, which you can export here:\n\n```bash\nexport DOCKER_CAPTAIN_PROJECTS=/path/to/your/deployments  # takes precedence over the config file\n```\n\nDetection 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.\n\n### ⚙️ Project Management via `manage`\n\nUse the `docker-captain manage` command to interactively select which projects should be considered *active*.\nYou’ll see a multi-select list of all detected projects — you can check or uncheck them using the keyboard, then confirm with Enter.\n\nThe selected projects become your *active fleet*, used by commands like `rally` and `abandon`.\n\n### 🚢 Easy Interaction with Single Projects\n\nNeed to start or stop one project?\nUse these straightforward commands:\n\n```bash\ndocker-captain start calibre --detach --remove-orphans\ndocker-captain stop calibre --remove-orphans\ndocker-captain restart calibre\n```\n\nThey’re thin wrappers around standard `docker compose` commands (`up`, `down`, and `restart`), but automatically use the correct compose file and folder context.\n\nFlags:\n\n* `-d` / `--detach`: Run containers in background.\n* `--remove-orphans`: Remove orphaned containers not defined in the compose file.\n\n### 📋 Listing Projects with `list`\n\nSee all detected projects neatly formatted in a Rich table:\n\n```bash\ndocker-captain list\n```\n\nThis shows:\n\n* **Project** name\n* Whether it’s **Active** (selected via `manage`)\n* Whether it’s currently **Running** (`docker compose ls` is checked behind the scenes)\n\nYou can also view the compose file paths with `--verbose`:\n\n```bash\ndocker-captain list --verbose\n```\n\n### ⚓ Rally and Abandon Your Fleet\n\nOnce you’ve marked projects as *active* using `manage`, you can control them all together:\n\n* **Start all active projects:**\n\n  ```bash\n  docker-captain rally --detach\n  ```\n* **Stop all active projects:**\n\n  ```bash\n  docker-captain abandon\n  ```\n\nThese 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.\n\n---\n\n## 📦 Installation\n\nYou can install `docker-captain` using `uv`, `pipx`, or plain `pip`.\n\n```bash\n# Install with\nuv tool install docker-captain\npipx install docker-captain\n\n# or try it out with\nuvx docker-captain\n```\n\n---\n\n## 🗒️ Configuration\n\n`captain-docker` support a simple YAML config file with the following structure:\n\n```yaml\n# ~/.config/docker-captain/config.yaml (on Linux)\nprojects_folder: /path/to/your/deployments  # environment variable: DOCKER_CAPTAIN_PROJECTS_FOLDER\n```\n\nThis configuration file can be generated interactively by running `captain-docker configure`.\n\n---\n\n\n## 🧭 Folder Structure Example\n\nYour deployments might look like this:\n\n```\n~/Deployments/\n├── calibre/\n│   └── compose.yaml\n├── immich/\n│   ├── compose.yaml\n│   └── immich.env\n├── paperless-ngx/\n│   ├── compose.yaml\n│   └── paperless-ngx.env\n└── syncthing/\n    └── compose.yaml\n```\n\nEach subfolder is automatically detected as a project if it has a Compose file.\n\n---\n\n## 🧠 Tech Stack\n\n| Library                                            | Purpose                      |\n| -------------------------------------------------- | ---------------------------- |\n| [Typer](https://typer.tiangolo.com/)               | CLI framework                |\n| [Rich](https://rich.readthedocs.io/)               | Beautiful terminal output    |\n| [Questionary](https://github.com/tmbo/questionary) | Interactive prompts          |\n| [sh](https://amoffat.github.io/sh/)                | Simple subprocess management |\n| [PyYAML](https://pyyaml.org/)                      | YAML parsing                 |\n\n---\n\n## 🐙 Example Workflow\n\n```bash\n# Detect and list all projects\ndocker-captain list\n\n# Choose which projects are active\ndocker-captain manage\n\n# Start all active projects\ndocker-captain rally -d\n```\n\n---\n\n## 💡 Inspiration\n\nI've been using `docker-compose.yaml` files to manage my home server for a while.\nI found the internet is full of tools to observe docker deployments, but I couldn't find one to manage my Docker Compose files.\nI wanted something simple, lightweight, and portable.\n\nI 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.\nGiven 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`.\n\nHope this is useful to someone, happy sailing! ⛵\n\n---\n\n## 🔧 Development\n\nIf you want to contribute to the project, please start by opening an [issue](https://github.com/lucabello/docker-captain/issues).\n\nYou can interact with the project via `uv` and the `justfile` (from [casey/just](https://github.com/casey/just)) at the root of the repository.\nSimply run `just` to show the available recipes.\n\n```bash\n# Create a virtual environment for the project\nuv venv --all-groups\nsource .venv/bin/activate\n\n# Linting, formatting, etc.\njust  # show the list of all commands\njust lint\n\n# Run docker-captain from the local folder\nuv run docker-captain\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucabello%2Fdocker-captain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucabello%2Fdocker-captain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucabello%2Fdocker-captain/lists"}