Server layout

Dockflow keeps no database. Besides the switch, the registry and the watchdog, it runs no service of its own. All of its state for a server lives on that server: in /var/lib/dockflow, and in labels on the Docker objects it creates.

This page lists everything Dockflow creates on a server, so you can inspect it, back it up or remove it. The state format is specified in the state specification.

The state directoryCopy Anchor Link

/var/lib/dockflow/
├── server.json                       the server's settings
├── server.lock                       held while the switch's configuration changes
├── user-data-host-key                empty; present when server cloud-init prepared the server: the filter keeps containers from the metadata service
├── switch/routes/<stack>.json        the routes the switch serves for each app environment
├── backups/
│   ├── <repository>.password         a backup repository's password, when Dockflow generated it
│   └── <repository>.pruned           when restic last reclaimed the repository's space
└── apps/<stack>/
    ├── lock                          held by the running agent
    ├── lock.json                     who holds the lock
    ├── manual-lock.json              present while a manual lock is held
    ├── env.json                      current and previous release
    ├── releases/<seq>.json.gz        one record per release
    ├── configs/<name>-<hash12>       Compose configs, by content
    ├── secrets/<name>-<hash12>       copies of the Compose secret files, for the watchdog
    ├── watchdog.json                 the watchdog's latest restarts
    ├── backup.json                   what a backup or a restore in progress changed
    └── uploads/
        ├── blobs/<sha256>            uploaded files, and the files uploads replaced
        └── manifests/<digest>.json   what each upload and its replaced files contain

/run/dockflow/secrets/<stack>/        on a tmpfs, 0700
└── <name>-<hash12>                   Compose secrets, by content and permissions

/etc/dockflow/
├── filter.rules                      the port filter's IPv4 rules, for iptables-restore
└── filter6.rules                     its IPv6 rules
/etc/systemd/system/dockflow-filter.service   loads them at boot, before Docker
/etc/systemd/system/dockflow-cloudflare.timer  downloads Cloudflare's ranges every week (cloudflare edge)
/etc/systemd/system/dockflow-cloudflare.service  the unit the timer starts
/usr/local/libexec/dockflow-cloudflare-refresh the script it runs: an agent run

In these paths:

• <stack> is <app>-<env>, for example shop-production;
• <seq> is the release number, written with 6 digits in file names (000042.json.gz);
• <repository> is local for the dockflow-backups volume, or the first 16 hex digits of the sha256 of the repository's URL.

About the files under /var/lib/dockflow:

• Owner. Only agent containers write here, as root. The directory is 0700 and its files 0600: only root on the server can read them.
• Atomic writes. Every file is written to <name>.tmp-<run-id>, synced, then renamed, so a crash never leaves a half-written file.
• Format. Every JSON document carries "schema": 1. The format changes only in a major release of Dockflow.
• Clocks. Timestamps are informational, in UTC, from the server's clock. No decision depends on them.

Files server init writes outside the stateCopy Anchor Link

Preparing a server (server init <admin>@<host>, sudo dockflow server init, or the user-data of server cloud-init) also writes the files below. server uninstall leaves them in place, as it does the boot units above. It removes the filter's rules, so the filter unit then loads nothing.

server.jsonCopy Anchor Link

Written by dockflow server init:

{
  "schema": 1,
  "name": "main",
  "edge": "external",
  "switch_image": "caddy:2.11.7@sha256:…",
  "switch_listen": "127.0.0.1:8080",
  "trusted_proxies": ["10.0.0.0/8"],
  "registry_image": "registry:3.1.2@sha256:…",
  "dockflow_version": "1.0.0-alpha.6",
  "watchdog_image": "sha256:…",
  "ssh_port": 22,
  "cloudflare_ranges": ["173.245.48.0/20", "…"],
  "filter_rules": "9f2c…"
}

Fields that are not always present:

• acme_email and acme_ca are present when server init --acme-email or --acme-ca set them.
• switch_listen and trusted_proxies are present with the external edge only.
• switch_image is absent when the server runs no switch (--edge none), and registry_image when it runs no registry (--no-registry).
• no_port_filter and no_watchdog record that server init was asked to leave the filter or the watchdog out. watchdog_image is absent without the watchdog.

filter_rules is the digest of the port filter's rules last applied, so a deploy that changes no port leaves the filter alone.

LocksCopy Anchor Link

• apps/<stack>/lock is an empty file. A run takes it with flock and holds it until the agent exits. If the agent dies, the kernel releases it. A second run fails with lock.held (exit code 5), or waits with --wait-lock.

• apps/<stack>/lock.json names the holder, for the error message:

  Copy Text

  { "schema": 1, "run": "01jbx6k3m8w0v7c9q2r5t4y6z8", "op": "deploy", "by": "alice@laptop", "ci": "github", "since": "2026-10-26T14:03:11Z" }

  ci is the CI provider, absent outside CI.

• apps/<stack>/manual-lock.json exists while dockflow lock acquire holds the environment, with the same fields and the message of -m. Every run refuses to start while it exists, unless given --force. It never expires: dockflow lock release removes it.

• apps/<stack>/backup.json exists while a backup or a restore has a service stopped or quiesced, or its volumes being replaced. The watchdog, or the next run that takes the lock, finishes it if the agent died: see Backups.

env.json and releasesCopy Anchor Link

{ "schema": 1, "last_seq": 42, "current": 42, "previous": 41, "degraded": false }

env.json points to the current and previous release.

Each releases/<seq>.json.gz is a gzipped JSON record of one release. It holds who made it and from which commit, its status, and the complete desired state of the app: every container's specification, with images pinned by digest. A rollback recreates containers from it. Values interpolated into a container's environment are part of that specification, as they are in docker inspect.

A release's status is applying while a run works on it, then active, then superseded when a newer one goes live. A failed run leaves rolled_back or failed, and a run whose agent died is marked abandoned by the next run.

After a successful run, the agent keeps the newest releases.keep releases that went live, and every release newer than the oldest of those. It deletes the other records. It then deletes the images, registry manifests and upload contents that no kept release uses.

ContainersCopy Anchor Link

The release number in a container's name is not padded: shop-production-web-42-1.

ImagesCopy Anchor Link

LabelsCopy Anchor Link

Every container, network and volume of an app carries Compose's own labels, so Docker tools see the environment as a Compose project:

Dockflow's own labels:

You can list an environment's containers with Docker itself:

docker ps -a --filter label=com.docker.compose.project=shop-production
docker compose -p shop-production ps

Networks and volumesCopy Anchor Link

App networks and volumes keep Compose's names: <stack>_default, <stack>_<network>, <stack>_<volume> (for example shop-production_pgdata). Networks and volumes marked external: true are used as they are, never created or removed.

• The switch joins the networks of the services it routes to, so it reaches them by name.
• An agent joins the app's networks during its run, to run internal health checks, and leaves them at the end.

Dockflow's own volumes:

PortsCopy Anchor Link

The switch's admin API listens on no port at all, only on a unix socket.

Removing everything by handCopy Anchor Link

dockflow destroy removes one environment: its containers, routes, networks and state, and with --volumes its data. dockflow server uninstall removes Dockflow from a server entirely, in one command.

To do the same by hand:

Deleting /var/lib/dockflow while the containers still run does not stop your services, but Dockflow loses their release history: there is nothing left to roll back to.