Lightweight Compose operations

Docker Compose,
kept manageable.

Control stacks, inspect services, protect data, and deploy releases without installing a heavyweight management platform.

Get started Read the docs

Python 3.10+ · Docker or Podman · Linux, macOS, Windows

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 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.

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.

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 log

Operate

stack upstack downstack updateservice connect

Protect

volume backupvolume restoreimage backupimage restore

Deliver

deployupdateinitcompletion

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.

FAQ

Small tool, clear boundaries.

Docker only?

No. compman auto-detects Docker Compose, Podman Compose, legacy docker-compose, and podman-compose.

Where is configuration stored?

A project-local compman.yml describes the stack, Compose files, profiles, managed directories, and optional deploy source.

How are secrets handled?

compman can inject environment variables from AWS Secrets Manager at command time, so secrets never need to live in compman.yml.

Are archive deployments safe?

Archive extraction rejects absolute paths, traversal, and links. Managed-tree replacement rolls back if its file swap fails. An optional SHA-256 pin verifies the download before extraction, so a bad artifact never reaches your project.

Is there a daemon or server?

No. compman is an on-demand CLI that delegates container operations to the detected local runtime.

Docker Compose,kept manageable.