Introduction
What Dockflow is, who it is for, how it works in a few lines, what it leaves out, and its current status.
Dockflow deploys a Docker Compose app to your own server over SSH.
You keep your compose.yml, add a short dockflow.yml, and run dockflow deploy from your laptop or from CI. Dockflow builds what changed and shows a plan. It starts the new containers next to the old ones and moves the traffic once they are healthy. When something fails, it rolls back on its own.
On the server, each app is a plain Compose project: docker compose -p <app>-<env> ps and logs work on it.
Quickstart
From a server to a first deploy in about ten minutes.
Install the CLI
curl, Homebrew, npm or PowerShell.
Who it is for
| You are | Typical setup | What Dockflow gives you |
|---|---|---|
| A solo developer | One server, one to five apps | dockflow deploy, HTTPS with automatic certificates, rollbacks |
| A small team | One server per environment, a few apps, CI | A plan before every change, a lock against concurrent deploys, rollback in one command |
| An agency | Several servers, many client apps sharing them | One switch per server in front of every app, each app in its own Compose project |
If you already deploy with docker compose up over SSH, Dockflow keeps that model. It adds zero-downtime rollouts, releases, rollback, secrets from CI and HTTPS.
Principles
Your Compose file, as written. The file that runs with docker compose up on your laptop is the one Dockflow deploys. Dockflow's own settings go in dockflow.yml and, per service, under x-dockflow, a key Compose ignores. Single-host features such as depends_on, 127.0.0.1: port bindings, devices and network_mode work as Docker defines them.
A plan before every change. Dockflow compares your files with what the server actually runs. dockflow plan prints the difference. dockflow deploy shows it and, on a terminal, asks before applying it. A service whose definition did not change keeps its containers.
Zero downtime by default. A service with a route gets new containers next to the old ones. The switch, a Caddy proxy on the server, moves traffic only once the new containers are healthy. The old ones get time to finish the requests in flight. See rollouts.
A deploy that always finishes. The deploy runs on the server, in a short-lived container called the agent. If your laptop sleeps, the network drops or the CI runner dies, the agent still finishes the deploy or rolls it back. Each deploy is recorded as a release you can roll back to. See releases and rollbacks.
One server per environment. An environment, such as production or staging, is one Linux server running Docker Engine. There is no cluster and no orchestrator. Scaling up means a bigger server first.
Only Docker on the server. Dockflow installs no daemon on the host. It talks to Docker through the Engine API over SSH. What it runs there are containers: the switch, a local registry, and the agent during a deploy. Its state is a few files under /var/lib/dockflow. See how it works.
The same from a laptop or CI. The dockflow CLI is a single binary. The same commands work on your machine and in any CI. In CI, one secret per environment holds the connection to the server.
Errors, not guesses. An unknown key, a variable with no value, an unsupported Compose feature or an unverified SSH host key stops Dockflow with an error. It never falls back to a silent default.
What Dockflow does not do
These are deliberate choices:
- No orchestrator. No Swarm, no Kubernetes, no Nomad. Dockflow drives plain Docker containers on one host.
- No multi-server environments. Dockflow does not schedule containers across servers or build a network between them. Several independent servers per environment may come after 1.0.
- No server creation. Dockflow does not call cloud provider APIs. You bring the server.
- No metrics or log storage.
dockflow logsstreams logs from the server. Storing them is the job of the tools you already use. - No user management. Whoever holds an environment's SSH key can deploy to it. Access to Docker is root on the server, and Dockflow does not pretend otherwise. See security.
- No platform on the server. No database, web UI or daemon to operate.
Status
Alpha The current release is 1.0.0-alpha.6.
What works today:
- zero-downtime deploys with the
switch,start-firstandstop-firststrategies, health checks, automatic rollback, releases anddockflow rollback; - HTTPS with automatic certificates (the
builtinedge), behind your own nginx (external), or behind Cloudflare (cloudflare); - image builds with buildx bake or Podman, locally or on the server, pushed to a registry on the server or an external one;
- jobs such as migrations, health checks, hooks, templates, file uploads and webhooks;
- secrets from CI, Compose
secrets:andconfigs:, and SOPS files; - server setup in one command, with a port filter, a watchdog and optional SSH hardening;
- several apps on one server, with shared networks and volume plugins;
- backups with restic, and restores, including production's data into staging;
- day-2 commands:
logs,exec,run,cp,ssh,ps,status,restart,scaleand more; - deploys from any CI, a GitHub Action, and an MCP server for AI assistants.
The configuration (version: 1), server state and event formats are specified and stable. They are frozen from 1.0.0, after which they change only by additions. The roadmap lists what is left before 1.0.0.
Coming from the earlier Dockflow, built on Docker Swarm? This version is a rewrite: see migrating.