Dockflow

Installation

Install the dockflow CLI on Linux, macOS or Windows, check it, enable shell completion, and prepare a server that meets the requirements.

Dockflow is one binary, dockflow. Install it on the machine you deploy from: your laptop or a CI runner.

Nothing is installed on the server's host. The CLI brings what it needs there as containers.

Install the CLI

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

This installs the newest release. To install a given version, pass --version:

curl -fsSL https://raw.githubusercontent.com/Shawiizz/dockflow/main/install.sh | sh -s -- --version v1.0.0-alpha.6

What the installer does

install.sh detects your system (Linux or macOS, amd64 or arm64), then:

  1. downloads SHA256SUMS and the binary dockflow-<os>-<arch> from the GitHub release;
  2. if cosign is installed, verifies the Sigstore signature of SHA256SUMS, which must come from the repository's release workflow. Without cosign, it says so and checks the checksum only, unless the signature is required (--require-signature): it then stops;
  3. checks the binary against SHA256SUMS, and stops if it does not match;
  4. installs it as dockflow in /usr/local/bin if that directory is writable, and in ~/.local/bin otherwise. It tells you if the directory is not on your PATH. In GitHub Actions, it adds the directory to GITHUB_PATH.

It needs curl or wget, and sha256sum or shasum.

OptionEnvironment variableDefaultEffect
--version <tag> (-Version)DOCKFLOW_VERSIONThe newest releaseThe release to install, such as v1.0.0-alpha.6; the v is optional
--dir <path> (-Dir)DOCKFLOW_INSTALL_DIR/usr/local/bin, or ~/.local/bin (%LOCALAPPDATA%\Programs\dockflow on Windows)Where to install dockflow
--require-signature (-RequireSignature)DOCKFLOW_REQUIRE_SIGNATURE=1OffStop when cosign is not installed, instead of checking the checksum only. The GitHub Action installs cosign and sets it
–DOCKFLOW_RELEASES_URLhttps://github.com/Shawiizz/dockflow/releases/downloadWhere releases are downloaded from: a mirror holding <tag>/<file>

For example, to install into ~/bin without root:

curl -fsSL https://raw.githubusercontent.com/Shawiizz/dockflow/main/install.sh | sh -s -- --dir ~/bin

In CI, pin the version with --version so that a new release does not change your deploys unannounced. The CI guide has complete workflows.

Check the installation

dockflow version
dockflow 1.0.0-alpha.6

dockflow version production prints the version deployed to the production environment instead.

dockflow --help lists the commands. dockflow <command> --help shows the options of one command.

Shell completion

dockflow completion <shell> prints a completion script for bash, zsh, fish or powershell.

Needs the bash-completion package.

# current shell
source <(dockflow completion bash)
# every new shell, on Linux
dockflow completion bash > /etc/bash_completion.d/dockflow
# every new shell, on macOS with Homebrew
dockflow completion bash > $(brew --prefix)/etc/bash_completion.d/dockflow

Start a new shell for the change to take effect.

The agent binary

Each deploy runs the dockflow binary itself on the server, as the agent: a short-lived container (see How it works). The server needs the Linux binary of exactly your CLI's version, for the server's architecture. The CLI finds it this way:

  1. if DOCKFLOW_AGENT_BINARY is set, it uses the file at that path;
  2. if the CLI is itself the Linux binary for the server's architecture, it sends itself;
  3. otherwise (macOS, Windows, or Linux on another architecture), it downloads dockflow-agent-linux-<arch> from the release of its own version. It caches the file in your user cache directory, under dockflow/<version>/ (~/.cache/dockflow/ on Linux). DOCKFLOW_RELEASES_URL replaces the download URL here too.

The CLI checks the download before using it:

  • A released CLI contains the SHA-256 of the release's agent binaries, and checks the download against it. So a server only runs a binary from the same build as your CLI, whose origin the installer checked.
  • A CLI built from source with a version, without those checksums, checks the download against the release's SHA256SUMS.

The binary is sent only when the server does not already have the agent image of that version: once per version and per server.

A development build (make build) has no release to download from. To deploy from macOS or Windows with one, build the Linux binary too and point DOCKFLOW_AGENT_BINARY at it:

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o dockflow-linux-amd64 ./cmd/dockflow
export DOCKFLOW_AGENT_BINARY=$PWD/dockflow-linux-amd64

Server requirements

dockflow server init <admin>@<host> prepares a server from an administrator's account. On the server itself, run sudo dockflow server init. It:

  • installs Docker on Debian and Ubuntu if it is missing;
  • creates the deploy user and its key;
  • installs the switch and the registry.

It leaves SSH's settings and the rest of the server's security to you. --harden-ssh adds a drop-in that refuses passwords and lets root in by key only: see What provisioning sets up.

See the Quickstart. The server needs:

RequirementWhy
Linux on amd64 or arm64The agent is a Linux binary for one of these architectures
Docker Engine 27 or laterserver init installs it on Debian and Ubuntu; elsewhere, install it first. The CLI checks the version when it connects, and refuses older engines (exit code 4)
SSH as root or a user with passwordless sudo, for server init (or a root shell on the server)server init creates the deploy user dockflow, in the docker group, which every other command uses. Your own user in the docker group works too, with server connection. Dockflow reaches the Docker socket through SSH stream-local forwarding, which OpenSSH allows by default (AllowStreamLocalForwarding). If the server refuses it, Dockflow falls back to docker system dial-stdio, which needs the docker CLI on the server
A known SSH host keyEvery connection verifies it: pinned in the configuration or the connection string, or present in your ~/.ssh/known_hosts. Nothing is trusted on first use
Ports 80 and 443 free, for the builtin edgeThe switch publishes them and obtains TLS certificates. With the external edge, behind your own proxy, the switch listens on 127.0.0.1:8080 instead. See The switch and edges
Port 5959 free on loopbackThe server-local registry listens on 127.0.0.1:5959, unless you use --no-registry
Access to Docker HubTo pull the switch (caddy), registry (registry) and backup (restic/restic) images, at the versions Dockflow pins, and the public images of your apps

A user that can use Docker is root on the server: anyone holding its SSH key can start a privileged container. Use a dedicated user and key per environment. See Security.

On the machine you deploy from, building images needs Docker with buildx, or Podman. Apps that only use public images need neither. See Building images.

Next: the Quickstart takes you from a server with Docker to a first deploy.

Edit on GitHub

Introduction

What Dockflow is, who it is for, how it works in a few lines, what it leaves out, and its current status.

Quickstart

From a Linux server to a first zero-downtime deploy, a second deploy and a rollback.

On this page

Install the CLIWhat the installer doesCheck the installationShell completionThe agent binaryServer requirements