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

01

Stack & services

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

02

Safe backups

Back up and restore named volumes or container images with configurable gzip compression.

03

Useful diagnostics

Get human-readable or JSON health reports with status and doctor.

04

Simple deployments

Fetch an S3 prefix or archive, or a public HTTP archive, then optionally build and recreate.

05

Secret-safe config

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

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 a public HTTP archive.

S3 supports prefixes and archives. HTTP and HTTPS accept .tar.gz, .tgz, and .zip archives.

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. Authenticated URLs are not yet supported.

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.

Is there a daemon or server?

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