Compose

Your services are described in standard Compose files, read with the same loader as Docker Compose. Dockflow's own per-service settings go under the x-dockflow extension.

This page lists how each Compose key is handled, then every option of x-dockflow. Nothing is dropped silently:

• a key this version cannot apply is refused with exit code 3 (see exit codes);
• a key that has no meaning on one server is ignored with a warning.

ExampleCopy Anchor Link

services:
  web:
    build: .
    environment:
      DATABASE_URL: postgres://shop:${DB_PASSWORD}@postgres:5432/shop
    depends_on:
      migrate: { condition: service_completed_successfully }
      postgres: { condition: service_healthy }
    deploy:
      replicas: 2
    x-dockflow:
      routes:
        - domains: ["${DOMAIN}", "www.${DOMAIN}"]
          port: 3000
        - domains: ["${DOMAIN}"]
          path: /api
          port: 3000
          strip_prefix: true
      rollout:
        strategy: switch
        drain: 30s
      health:
        http:
          path: /healthz
          status: 200-399

  worker:
    build: .
    command: ["node", "worker.js"]
    x-dockflow:
      health:
        grace: 15s

  migrate:
    build: .
    command: ["node", "migrate.js"]
    environment:
      DATABASE_URL: postgres://shop:${DB_PASSWORD}@postgres:5432/shop
    depends_on:
      postgres: { condition: service_healthy }
    x-dockflow:
      run: before

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: shop
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes: [pgdata:/var/lib/postgresql/data]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U shop"]
      interval: 5s
    x-dockflow:
      stateful: true

volumes:
  pgdata: {}

With DOMAIN in the environment's vars and DB_PASSWORD as a secret, dockflow list services shows what this file becomes:

SERVICE   IMAGE               REPLICAS  STRATEGY     ROUTES
migrate   shop/migrate        1
postgres  postgres:16-alpine  1         stop-first
web       shop/web            2         switch       shop.example.com/ www.shop.example.com/ shop.example.com/api
worker    shop/worker         1         start-first

Files, profiles and variablesCopy Anchor Link

• Which files. The compose list of dockflow.yml, or of the environment, which replaces it. Without one, the first that exists of compose.yaml, compose.yml, docker-compose.yaml and docker-compose.yml. An app with no Compose file is valid.
• Several files are merged in order, as docker compose -f a.yml -f b.yml does. include and extends work as in Compose.
• Profiles. A service with profiles is deployed only when the environment lists one of its profiles under profiles. Services without profiles are always deployed.
• Project name. Always <app>-<env>. A top-level name in the Compose file has no effect.
• Interpolation. ${VAR}, ${VAR:-default}, ${VAR:?message} and $$, with Dockflow's variables: built-ins, secrets, then vars. A variable with no value and no default is an error. The Compose .env file is not read.
• environment: [KEY], a key without a value, takes the value of that variable.
• Relative paths, such as build.context and env_file, are relative to the folder of the first Compose file, as with docker compose -f deploy/compose.yml: a Compose file in deploy/ builds the project with context: ... env_file is read on your machine.
• Names on the server. Containers, networks and volumes are prefixed with the stack: the volume pgdata of shop in production is shop-production_pgdata. Networks and volumes with external: true keep their own name and must already exist on the server.
• x-* keys other than x-dockflow, at the top level or on a service, are ignored, so YAML anchors under x-common work.

Service keysCopy Anchor Link

BuildCopy Anchor Link

Services with build are built with docker buildx bake, or with Podman when build.engine: podman is set. The build runs on your machine, or on the server with build.builder: remote. See build and the building images guide.

Podman builds use context, dockerfile, dockerfile_inline, args, labels, additional_contexts, target, cache_from, cache_to, no_cache, pull, network, extra_hosts, ssh and shm_size.

Files listed under templates are rendered into a temporary copy of the build contexts before the build.

Image namesCopy Anchor Link

<version> is the release's version label (DOCKFLOW_VERSION), with characters other than letters, digits, _, . and - replaced by -. In the plan and in dockflow list services, a built service shows as <app>/<service> until it is built.

x-dockflowCopy Anchor Link

Dockflow's settings for one service. Values are interpolated like the rest of the file. Keys are matched exactly, in lower case. An unknown key, or a known one written in another case (Stateful), is an error.

routesCopy Anchor Link

Each route sends HTTP traffic from the server's switch to the service's containers, over the app's network. See the switch and edges.

# compose.yml (fragment)
services:
  panel:
    image: ghcr.io/acme/panel:2.0
    x-dockflow:
      routes:
        - domains: [panel.example.com]
          port: 8080
          headers:
            X-Frame-Options: DENY
            Strict-Transport-Security: max-age=31536000
            -Server: ""
          encode: [zstd, gzip]
          max_body: 25MB
          timeouts: { read: 90s }
          auth: { user: admin, password: "${PANEL_PASSWORD}" }
          caddy: |
            @ws header Connection *Upgrade*
            reverse_proxy @ws {upstream}:4327

The switch applies these options with every edge, behind nginx too. Changing them reloads the switch's configuration once; an ordinary deploy does not reload it.

A domain belongs to one app environment on a server, and a domain and path pair can be routed by one service only. When a second app claims a domain another app routes, at any path, or a service claims a pair already routed, the plan fails with plan.domain_conflict, before anything changes. Domains are compared lower-cased and without a trailing dot, and paths without a trailing slash: /api/ is /api. Routes need a switch on the server, installed by dockflow server init.

Routes that do not target a service (redirects, proxies and files) go in routes: of dockflow.yml.

rolloutCopy Anchor Link

The default strategy, when neither strategy nor deploy.update_config.order is set:

A service that must use stop-first (the first row) refuses any other strategy. switch needs routes. See rollouts.

healthCopy Anchor Link

http:

A failed http check follows on_failure. A routed service with neither a healthcheck nor http gets a warning: it counts as healthy after grace. See the health checks guide.

statefulCopy Anchor Link

stateful: true marks a service that holds data. It runs as a single container and is replaced with stop-first, so two containers never write the same volume.

A deploy updates the stateful services before the others (but after what they depend on), so the data is there before what uses it. Only stateful services take backup, and destroy keeps their volumes unless --volumes is given.

runCopy Anchor Link

A job is a service run to completion on each deploy, in one container, never restarted. It fails the deploy unless it exits with code 0.

A service that another one waits for with depends_on: { condition: service_completed_successfully } is a before job, even without run. Jobs run on a deploy that changes something, in depends_on order. They do not run on rollback, restart or scale. See the jobs guide.

backupCopy Anchor Link

How a stateful service is backed up with restic. The keys are type (postgres, mysql, mongo, redis, volume or command), database, dump_options, restore_options, volumes, quiesce (stop, none or { exec: { pre, post } }), dump, restore, and the retention keep. Each option is described in the backups guide.

# compose.yml (fragment)
services:
  db:
    image: postgres:17
    x-dockflow:
      stateful: true
      backup: { type: postgres, keep: { daily: 14, weekly: 8 } }

Refused combinationsCopy Anchor Link

More examplesCopy Anchor Link

A job after the deploy, an unrouted service with an HTTP check, and a service that publishes a fixed port:

services:
  api:
    image: busybox
    command: ["httpd", "-f", "-p", "8080"]
    pull_policy: always
    stop_grace_period: 20s
    x-dockflow:
      rollout: { strategy: start-first }
      health:
        http: { port: 8080, path: /, status: "200", timeout: 2s, retries: 5, interval: 2s }

  notify:
    image: curlimages/curl:8.10.1
    command: ["curl", "-fsS", "https://hooks.example.com/deployed"]
    x-dockflow:
      run: after

  game:
    image: itzg/minecraft-server
    ports: ["25565:25565"]
    x-dockflow:
      rollout: { strategy: stop-first }

Several files, with a profile enabled in one environment only:

version: 1
app: shop
environments:
  production: {}
  staging:
    compose: [compose.yml, compose.staging.yml]
    profiles: [debug]

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