Docker Compose stack manager

Docker Compose,
kept manageable.

Q: Where is compman configuration stored?

In a project-local compman.yml file that describes the stack name, Compose files and profiles, managed directories, backup location, and an optional deploy source. Managed paths can never escape the directory that contains it.

Q: How does compman handle secrets?

Compose variables are declared as ${secrets:NAME} markers and resolved at command time from AWS Secrets Manager, so secret values never live in compman.yml. Deploy tokens and Slack webhook URLs are read from named environment variables for the same reason.

Q: Can I back up Docker volumes on a schedule?

Yes. compman schedule add registers an unattended volume backup job with the platform scheduler: launchd on macOS, schtasks on Windows, and a systemd user timer or crontab on Linux, with hourly, daily, weekly, or monthly cadences.

Q: Can I get notified when a deployment finishes?

Yes. Set COMPMAN_SLACK_WEBHOOK_URL or add a notify.slack block to compman.yml and stack up, stack update, and compman update post a Slack message with the stack, runtime, host, duration, unhealthy services, and named-volume sizes. A failed notification warns but never fails the command.

compman is a lightweight CLI that starts and updates Compose stacks, backs up volumes and container images, schedules unattended backups, deploys releases from S3 or HTTPS, reports health as JSON, and posts to Slack. No daemon, no web UI, no platform to maintain.

Get started Read the docs

Python 3.12+ · Docker or Podman · Linux, macOS, Windows · MIT license

operator@host

$ compman status
Stack payments is healthy
  api       running
  postgres  running

$ compman schedule add --daily 04:30
Backup created successfully

$ compman deploy --path release.zip
Deploy completed

For constrained environments

When a web GUI is unavailable, blocked by a firewall, or simply too heavy.

Dedicated to the brave souls managing everything with raw Docker commands because every other tool was somehow “not allowed.”

One focused tool

Common Docker Compose operations without the command archaeology.

Stack & services

Start, stop, update, inspect, connect to, and follow logs from Compose services.

Safe backups

Back up and restore named volumes or container images with configurable gzip or Zstandard compression. Point dirs.backup at an S3 URI to store archives in the cloud, schedule unattended backups, and rely on retention to keep the newest N per stack. Endpoint overrides make Ministack and LocalStack work.

Useful diagnostics

Get human-readable or JSON health reports with status and doctor, stable enough to gate a pipeline.

Simple deployments

Fetch an S3 prefix or archive, or an authenticated HTTPS archive, then optionally build and recreate. A SHA-256 pin verifies the artifact before anything changes.

Secret-safe config

Inject environment variables from AWS Secrets Manager instead of hardcoding secrets in compman.yml.

Scheduled backups

Register platform-native jobs (launchd, systemd, cron, schtasks) that run volume backups on a cadence you choose — hourly, daily, weekly, or monthly.

Slack notifications

Post a message when a stack comes up, with the host, runtime, elapsed time, unhealthy services, and named-volume sizes. Delivery never fails the command.

Multi-stack registry

Remember deployed stacks and run any command against them from any directory with --stack NAME.

Use cases

The jobs people actually install a Compose manager for.

Every item below is a concrete task, not a feature label.

Back up a Docker volume

Snapshot a named volume to a timestamped .tar.gz (or .tar.zst) archive, then restore it onto another host or into a fresh stack. The stack is paused during the transfer unless you opt out.

compman volume backup · compman volume restore

Check whether the stack is healthy

Get per-service state and health as readable text or as versioned JSON. status exits non-zero when the stack is missing, which makes it usable as a CI or monitoring gate.

compman status --json · compman doctor --json

Deploy a release archive

Point a stack at an S3 prefix or an HTTPS archive and let deploy or update fetch it, verify it, build, swap the managed tree, and recreate. Roll back to the previous release in one command.

compman deploy --build · compman rollback

Back up every night on a server

Register a volume backup with the platform scheduler so it runs unattended. Works the same on macOS launchd, Windows schtasks, and Linux systemd timers or cron, and writes run records you can inspect later.

compman schedule add --daily 04:30 · compman schedule status

Know when a deploy finished

Send a Slack message the moment stack up or stack update brings a stack up, listing any unhealthy service and the size of each named volume. Useful on a headless host where nobody is watching the terminal.

compman stack up with COMPMAN_SLACK_WEBHOOK_URL

Keep a stack running without a server

compman adds no daemon and opens no port. It calls the Docker or Podman CLI you already have, so it fits locked-down hosts, jump boxes, and air-gapped networks where a management platform cannot be installed.

compman stack up --wait · compman ps · compman stats -f

Quick start

From Compose file to managed stack.

Install compman as an isolated tool, create a starting configuration, and bring the project up.

Explore configuration →

# Install from GitHub
uv tool install --force --managed-python git+https://github.com/allbegray/compman.git

# In your Compose project
compman init --scaffold
compman stack up
compman status
compman ps
compman stats -f

Command map

Predictable commands, grouped by what you manage.

Observe

statusdoctorpsstats -fservice statusservice loghistory

Operate

stack upstack downstack updatestack logsservice connect

Protect

volume backupvolume restorevolume pullimage backupimage restore

Deliver

deployupdaterollbackinitstacks list

View the full command reference

Bring your own release source

Deploy from S3 or authenticated HTTPS archives.

S3 supports prefixes and archives. HTTP and HTTPS accept .tar.gz, .tgz, and .zip archives. Pin any source with a SHA-256 digest: the download is verified before extraction, build, and the managed-tree swap, so a mismatch aborts with nothing changed.

S3-compatible storage

compman deploy --path \
  s3://my-bucket/releases/app.tar.gz \
  --build --tag my-app

Works with AWS S3 and endpoint-compatible services such as Ministack.

Public HTTP / HTTPS

compman deploy --path \
  https://example.com/releases/app.zip \
  --build --tag my-app

Streams the archive with standard TLS verification. Add an auth block and compman reads the header value from an environment variable at fetch time; the token is never stored in compman.yml, and cross-host redirects drop the header.

Install

One command, isolated from your Python environment.

compman is published on PyPI and installed as a self-contained tool, so it never touches your project dependencies.

uv

uv tool install compman

Recommended. Self-contained, and compman upgrade refreshes the stored install in place.

pipx

pipx install compman

Works the same way if pipx is already part of your tooling.

One-line scripts

curl -fsSL .../install.sh | sh
irm .../install.ps1 | iex

Bundled installers for Linux, macOS, and Windows that place the CLI on your PATH.

From source

uv tool install git+https://github.com/allbegray/compman.git

Tracks the main branch instead of a release, for testing unreleased changes.

FAQ

Small tool, clear boundaries.

Does compman work with Docker only?

No. compman auto-detects Docker Compose, Podman Compose, podman-compose, and the legacy docker-compose command, and you can force a runtime with CONTAINER_RUNTIME=podman.

Where is compman configuration stored?

In a project-local compman.yml file that describes the stack name, Compose files and profiles, managed directories, backup location, and an optional deploy source. Managed paths can never escape the directory that contains it.

How does compman handle secrets?

Compose variables are declared as ${secrets:NAME} markers and resolved at command time from AWS Secrets Manager, so secret values never live in compman.yml. Deploy tokens and Slack webhook URLs are read from named environment variables for the same reason.

Is archive deployment safe?

Archive extraction rejects absolute paths, path traversal, and links. Managed-tree replacement rolls back if the file swap fails, and an optional SHA-256 pin verifies the download before extraction, build, or any change to your project.

Does compman run a daemon or web server?

No. compman is an on-demand CLI that delegates container operations to the detected local runtime, so there is no background service to install, secure, or keep running.

Can I back up Docker volumes on a schedule?

Yes. compman schedule add registers an unattended volume backup job with the platform scheduler: launchd on macOS, schtasks on Windows, and a systemd user timer or crontab on Linux, with hourly, daily, weekly, or monthly cadences.

Can I get notified when a deployment finishes?

Yes. Set COMPMAN_SLACK_WEBHOOK_URL or add a notify.slack block to compman.yml and stack up, stack update, and compman update post a Slack message with the stack, runtime, host, duration, unhealthy services, and named-volume sizes. A failed notification warns but never fails the command.

Which Python version and operating systems are supported?

Python 3.12, 3.13, 3.14, and 3.15 on Linux, macOS, and Windows. The --zstd backup format requires Python 3.14, which ships the standard-library compression.zstd module.

When is compman the wrong tool?

compman has no web UI, no multi-host orchestration, no image registry, and no container metrics history. If you need a browser-based management console, scheduling across several hosts, or a built-in registry, a full platform fits better. compman is built for one host, driven from a terminal or a script.

Docker Compose,kept manageable.