dockflow.yml

dockflow.yml sits at the root of your project and describes the app and its environments. Your services stay in standard Compose files. dockflow.yml holds what Compose has no place for: the environments, the registry, the hooks, the checks and the uploads.

This page lists every key, section by section, starting with the top level. A complete example is at the end.

The format is strict: an unknown key is an error (exit code 3, see exit codes). Later 1.x versions may add keys, but never remove or rename one. A file that uses a newer key says so with requires. dockflow validate <env> checks the file, the Compose files and the variables without contacting a server.

ConventionsCopy Anchor Link

• Durations are written like 90s, 5m, 1h30m or 500ms (units ms, s, m, h).
• Paths are relative to the project directory, the one that holds dockflow.yml, and must stay inside it unless stated otherwise.
• String values are interpolated with Compose syntax (${VAR}, ${VAR:-default}, ${VAR:?message}, $$ for a literal $), except version, app, mapping keys and the values under environments.<env>.vars. See variables.

Top levelCopy Anchor Link

Keys an environment can overrideCopy Anchor Link

These top-level keys can also be set inside an environment, where they replace the top-level value for that environment (blocks are not merged key by key):

templates, registry, build, releases, on_failure, health, uploads, hooks, notify, firewall, plugins, routes, backups.

version, requires, app, compose and environments cannot be set inside an environment. An environment has its own compose key, which replaces the top-level list.

templatesCopy Anchor Link

Each entry is either a path, rendered in place, or a src/dest pair. Templates are rendered into a temporary copy of the build contexts and the upload sources: your source tree is never written to. An undefined variable is an error. The template syntax is in the templates guide.

registryCopy Anchor Link

Without this block, built images are pushed to the registry Dockflow runs on the server, through the SSH connection.

buildCopy Anchor Link

See the building images guide.

releasesCopy Anchor Link

on_failureCopy Anchor Link

A failure of the rollout itself (a container that exits, stays unhealthy or times out) always rolls back, whatever the value. See releases and rollbacks.

healthCopy Anchor Link

Public checks, run from the server after traffic has moved to the new release. They add to the per-service checks of x-dockflow.health.

Each entry of endpoints:

uploadsCopy Anchor Link

Files and directories copied to the server on each deploy, before the containers change. Only changed files are sent. See the uploads guide.

hooksCopy Anchor Link

Commands run at fixed points of a deploy. Hook commands are not interpolated. Instead, the built-in variables, the environment's vars and the secrets the hook lists arrive as environment variables. See the hooks guide.

Each hook sets exactly one of run, script, host and exec:

notifyCopy Anchor Link

Webhooks sent when a run finishes. See the notifications guide.

firewallCopy Anchor Link

The ports your services publish that the port filter lets in from outside. A port published on every interface (5432:5432) and not listed here is dropped, and the plan warns about it.

firewall:
  public_ports:
    - 25565                                            # tcp and udp, from anywhere
    - { port: 4326, protocol: tcp, from: [203.0.113.0/24] }

An entry of public_ports is a port number, or a map:

There is one filter per server. A port that one app lists is open, whichever container publishes it. The filter follows each app environment's current release, so a rollback restores the ports of the release it returns to.

pluginsCopy Anchor Link

Plugins to expand into this environment's uploads, templates and hooks. See the plugins guide.

plugins:
  - use: nginx
    with: { domain: "${DOMAIN}", cloudflare: true }
  - use: ./deploy/plugins/rclone
    id: archives
    with: { remote: "s3:archives" }

routesCopy Anchor Link

Routes the switch serves that don't target a service of the app. Each has exactly one of redirect, proxy and files.

routes:
  - domains: [example.com]
    path: /docs
    redirect: "https://docs.example.com{uri}"
  - domains: [api.example.com]
    proxy: http://billing-api:8080      # another app's service, on a shared network
    network: shared
  - name: maintenance
    domains: [example.com]
    path: /maintenance
    files: { host_path: /srv/maintenance }
  - domains: [files.example.com]
    files: { volume: archives, browse: true }
    auth: { user: team, password: "${ARCHIVES_PASSWORD}" }

A route also takes every option of a service's route: headers, encode, max_body, timeouts, auth, caddy and error_pages.

A files route runs a small file server, files-<name> (or files-<n>), in the switch's image. That file server mounts the directory read-only; the switch itself mounts nothing.

environmentsCopy Anchor Link

A map from environment name to its settings. At least one environment is required. An environment can be empty (production: {}) when its server comes from the <ENV>_CONNECTION secret.

It can also hold any of the keys an environment can override.

serverCopy Anchor Link

How Dockflow finds the server of an environment, first match wins:

1. the --connection option;
2. the <ENV>_CONNECTION secret (PRODUCTION_CONNECTION), printed by dockflow server connection;
3. the server block, with the private key from DOCKFLOW_SSH_KEY_<ENV>, DOCKFLOW_SSH_KEY (the key itself, or a path to it), ssh-agent, or the IdentityFile your ~/.ssh/config gives the host.

Dockflow reads HostName, Port, User and IdentityFile from ~/.ssh/config as OpenSSH does: Host patterns (with *, ? and !), Include, and the first value of each keyword. Match blocks are skipped. What server: sets wins over the file.

backupsCopy Anchor Link

Where the environment's backups go. Without this block, backups go to a restic repository on the server, in the dockflow-backups volume, with a password Dockflow generates.

backups:
  repository: s3:s3.eu-west-1.amazonaws.com/acme-backups/${DOCKFLOW_APP}
  password: ${RESTIC_PASSWORD}
  env:
    AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}
    AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}

Naming rulesCopy Anchor Link

On the command line, an environment can be shortened to a unique prefix: dockflow deploy prod deploys production. When dockflow.yml has a single environment, it can be left out.

VariablesCopy Anchor Link

Values are written in the syntax native to each file:

A variable with no value and no default is an error, in both syntaxes.

Lookup orderCopy Anchor Link

For an environment, here production, a variable is looked up in this order, and the first match wins:

1. Built-in variables:

   Variable	Value
   DOCKFLOW_APP	The app name
   DOCKFLOW_ENV	The environment name
   DOCKFLOW_STACK	<app>-<env>
   DOCKFLOW_VERSION	The release's version label: --version, else the version of the CI tag, else the short commit (with -dirty when the tree has changes), else the UTC time of the deploy
   DOCKFLOW_GIT_SHA	The full commit, empty outside git
   DOCKFLOW_GIT_BRANCH	The branch, empty on a detached checkout unless the CI provider gives it
   DOCKFLOW_SERVER	The server's name (main by default)

2. Secrets. The key X is looked up as PRODUCTION_X, then X, in each source in turn:

   1. the process environment, of which only PRODUCTION_* variables are read, and the JSON object in DOCKFLOW_SECRETS;
   2. the file .env.dockflow at the project root (KEY=value lines, values taken literally);
   3. the environment's SOPS file, when there is one.

3. The environment's vars.

Names with a double underscore right after the environment's prefix, such as PRODUCTION__DB__PASSWORD, are reserved for per-server values, for when an environment has several servers. Do not define such variables.

Interpolating DOCKFLOW_VERSION or DOCKFLOW_GIT_SHA into a service changes its spec on every commit, so that service is restarted by every deploy.

A complete exampleCopy Anchor Link

This file and its Compose files pass dockflow validate for both environments, with the secrets GHCR_TOKEN, JWT_PRIVATE_KEY and WEBHOOK_SECRET set (for example PRODUCTION_GHCR_TOKEN=…).

version: 1
app: shop

# Compose files, merged in order.
compose: [compose.yml]

# Rendered with Jinja into a temporary copy, before the build and the uploads.
templates:
  - src: config/app.conf.tpl
    dest: config/app.conf
  - nginx/default.conf              # rendered in place, in the copy

# Without this block, images go to the server's own registry.
registry:
  url: ghcr.io/acme                 # images are ghcr.io/acme/shop/<service>
  username: acme-bot
  password: ${GHCR_TOKEN}           # a secret: PRODUCTION_GHCR_TOKEN in CI
  additional_tags: ["${DOCKFLOW_ENV}-latest"]

build:
  builder: local                    # local or remote
  engine: docker                    # docker or podman

releases:
  keep: 10                          # at least 2

on_failure: rollback                # rollback, fail or ignore

# Public checks, after the switch.
health:
  startup_delay: 5s
  endpoints:
    - name: site
      url: https://${DOMAIN}/
      expected_status: 200
      timeout: 30s
      retries: 3
      retry_delay: 5s

uploads:
  - src: public
    dest: volume:static             # a volume of the Compose file
    mirror: true                    # delete what is not in public/
    exclude: [.git, "*.map"]
  - src: deploy/backup.timer
    dest: /etc/systemd/system/shop-backup.timer
    mode: "644"

hooks:
  before_build:
    - run: ./scripts/generate-keys.sh
      secrets: [JWT_PRIVATE_KEY]    # arrives as an environment variable
  before_deploy:
    - name: clear cache
      service: web
      exec: ["sh", "-c", "rm -rf /var/cache/nginx/*"]
      timeout: 2m
  after_deploy:
    - host: sudo systemctl daemon-reload
      fatal: false

notify:
  - url: https://hooks.example.com/dockflow
    on: [failure]
    secret: ${WEBHOOK_SECRET}
    headers: { X-Team: shop }
    timeout: 10s

environments:
  production:                       # server from the PRODUCTION_CONNECTION secret
    vars:
      DOMAIN: shop.example.com
    deploy:
      timeout: 15m
  staging:
    server:                         # instead of a STAGING_CONNECTION secret
      host: 203.0.113.20
      user: dockflow
      host_key: "SHA256:2kVJbNxZ4m8l9Pq0vXyQ1sXJmVf5tZ8b3c7d6e5f4g0"
    compose: [compose.yml, compose.staging.yml]
    profiles: [debug]
    vars:
      DOMAIN: staging.shop.example.com
    on_failure: fail                # replaces the top-level value
    releases:
      keep: 3
    ci:
      tag_suffix: staging           # the tag 1.2.0-staging deploys here

services:
  web:
    build: .
    volumes: [static:/usr/share/nginx/html]
    x-dockflow:
      routes:
        - domains: ["${DOMAIN}"]
          port: 80
      health:
        http: { path: / }

volumes:
  static: {}

services:
  debug:
    image: busybox
    command: ["sleep", "infinity"]
    profiles: [debug]