Quickstart

Check the prerequisites.

You need:

• a Linux server (amd64 or arm64), new or already in use. Dockflow installs Docker on Debian and Ubuntu. On another distribution, install Docker Engine 27 or later first;
• SSH access to it as root or as a user with passwordless sudo, or a root shell on it;
• ports 80 and 443 of the server free and reachable from the internet;
• a domain name whose DNS record points to the server. This guide uses hello.example.com.

The full list is in server requirements. If an nginx on the server already holds ports 80 and 443, follow behind nginx for the server part.

Install the CLI on your machine.

curl -fsSL https://raw.githubusercontent.com/Shawiizz/dockflow/main/install.sh | sh
dockflow version

Homebrew, npm, Windows and other options are in installation.

Prepare the server. Run server init from your machine or on the server itself. The result is the same.

dockflow server init [email protected]

  connecting to 203.0.113.10:22 as root
  installing Docker from download.docker.com (debian bookworm)
  creating the user dockflow
  adding dockflow to the docker group
  installing the deploy key of dockflow
  connecting as dockflow with the deploy key
  installing the agent image dockflow/agent:1.0.0-alpha.6
✓ 203.0.113.10 is ready (edge: builtin, deploy user: dockflow)

The connection string below holds the deploy key: store it as the <ENV>_CONNECTION secret
…

eyJ2IjoyLCJzZXJ2ZXJzIjpb…

server init:

• installs Docker when it is missing, from Docker's own repository;
• creates the deploy user dockflow, in the docker group, with an SSH key restricted to what Dockflow uses. The private key is never written on the server;
• reconnects as dockflow and installs the switch (dockflow-switch, a Caddy container that publishes ports 80 and 443 and obtains certificates) and the server-local registry (dockflow-registry, on 127.0.0.1:5959);
• prints the connection string: the server, its host key and the deploy key, in one value.

It leaves SSH's settings alone. Add --harden-ssh to turn passwords off and let root in by key only, once your account has a key.

You can run it again at any time. On a prepared server, it changes nothing.

Create a directory for the project. Store the connection string in a local .env.dockflow file, kept out of git. In CI, it becomes the PRODUCTION_CONNECTION secret (see deploying from CI).

PRODUCTION_CONNECTION=eyJ2IjoyLCJzZXJ2ZXJzIjpb…

echo .env.dockflow >> .gitignore

Describe the environment.

Write dockflow.yml at the root of the project. The server comes from the connection string, so the file does not mention it:

version: 1
app: hello

environments:
  production:
    vars:
      DOMAIN: hello.example.com

Describe the app.

Write compose.yml next to dockflow.yml. It is a standard Compose file. The x-dockflow key, which Compose ignores, adds a route.

services:
  web:
    image: nginx:1.27-alpine
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://127.0.0.1/"]
      interval: 5s
      timeout: 3s
      retries: 3
    x-dockflow:
      routes:
        - domains: ["${DOMAIN}"]
          port: 80

• ${DOMAIN} takes its value from the environment's vars.
• The route sends https://hello.example.com to port 80 of the container.
• The healthcheck tells Dockflow when a new container is ready for traffic.

dockflow init --domain hello.example.com writes these two files for you. With --ci github or --ci gitlab, it also writes a CI workflow (see init).

Check the project without touching the server:

dockflow validate production

production: valid, 1 services

Look at the plan.

dockflow plan production

Plan: 1 to create, 0 to update, 0 to remove
  · network.create hello-production_default: does not exist
  + service.create web [switch]: new service
  · routes.apply hello-production: routes changed

The plan is computed from what the server actually runs. Nothing is changed yet.

Deploy.

dockflow deploy production

On a terminal, deploy shows the same plan and asks for confirmation. -y skips the question, and CI never asks.

Then the agent, a short-lived container on the server, starts web, waits for its healthcheck, points the route at it, and records release 1. The switch obtains a certificate for hello.example.com from Let's Encrypt on its own.

curl https://hello.example.com/

Since dockflow.yml has a single environment, you can leave out production in every command.

Check the status.

dockflow status production

It shows the current release, its version label and the containers of each service. The version label is the short git commit, or the time of the deploy outside a git repository.

dockflow ps lists the containers, and dockflow logs web shows their logs.

Change something and deploy again.

Change the image tag in compose.yml:

services:
  web:
    image: nginx:1.28-alpine

dockflow deploy production

Plan: 0 to create, 1 to update, 0 to remove
  ~ service.update web [switch]: image nginx@sha256:… → nginx@sha256:…

The new container starts next to the old one. Once it is healthy, traffic moves to it. The old container gets 30 seconds to finish the requests in flight, then stops. No request fails during the switch.

Deploying again without a change prints Nothing to change. and creates no release.

Roll back.

dockflow rollback production

This restores the previous release, with the same zero-downtime switch. It uses the image still on the server, so nothing is rebuilt or downloaded. The rollback is itself a new release:

dockflow releases production

SEQ  VERSION  STATUS                     CREATED               BY
3    a1b2c3d  active (rollback to 1)     2026-10-26T14:12:40Z  alice  ← current
2    e4f5a6b  superseded                 2026-10-26T14:08:02Z  alice
1    a1b2c3d  superseded                 2026-10-26T14:03:11Z  alice

dockflow rollback --to 2 would restore release 2.