Migrating from the earlier Dockflow

This page moves a project from the earlier Dockflow to this one. The earlier Dockflow is the TypeScript tool built on Docker Swarm, with releases up to 3.1.1; this page calls it 1.x.

This version is a rewrite and shares nothing with 1.x: not the configuration format, not the CLI, not what it keeps on the server. It never reads a 1.x file or server, and has no migrate command. You move a project by hand, with the table below.

The serverCopy Anchor Link

The simplest path is a fresh server, prepared with dockflow server init as in the quickstart. Keep the old server running until the new one serves the app, then move the DNS.

To reuse the 1.x server, remove 1.x from it first:

1. Copy what you want to keep out of /var/lib/dockflow. This version writes its own state there and does not read 1.x's.
2. Remove the Swarm stacks (docker stack rm), Traefik, and the port filter rules and units.
3. Leave the swarm: docker swarm leave --force.
4. Run dockflow server init as for a new server.

If a Swarm stack left behind a network with the name your app uses, the plan refuses it until you remove it.

The data in your named volumes stays where it is, but the volume names may change: this version names volumes <app>-<env>_<volume>. To keep the data, either:

• copy it across with a backup and dockflow backup restore, or with dockflow cp;
• or declare the old volume with external: true and its name.

The projectCopy Anchor Link

There is no Swarm, so a few Compose keys that only Swarm used change meaning:

• deploy.placement, deploy.endpoint_mode and deploy.rollback_config are ignored with a warning;
• deploy.mode: global runs one container;
• external secrets and configs are refused: give them a file, environment or content source.

The Compose reference lists every key.

Step by stepCopy Anchor Link

A complete exampleCopy Anchor Link

A backend with Postgres, which 1.x deployed as an app and an accessory. Both services also join a network shared with another app:

services:
  backend:
    build: .
    environment:
      QUARKUS_DATASOURCE_JDBC_URL: jdbc:postgresql://postgres:5432/app
      QUARKUS_DATASOURCE_USERNAME: app
      QUARKUS_DATASOURCE_PASSWORD: ${DB_PASSWORD}
      PAYMENT_API_KEY: ${PAYMENT_API_KEY}
    networks: [default, shared]
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8081/q/health"]
      start_period: 40s
    x-dockflow:
      routes:
        - domains: [api.example.com]
          port: 8081
          max_body: 25MB

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: app
    volumes: [postgres_data:/var/lib/postgresql/data]
    networks:
      default: {}
      shared: { aliases: [backend-db] }
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
    x-dockflow:
      stateful: true
      backup: { type: postgres, keep: { daily: 14, weekly: 8 } }

networks:
  shared: { external: true }   # dockflow server network create shared

volumes:
  postgres_data: {}

version: 1
app: backend
hooks:
  before_build:
    - script: .dockflow/hooks/pre-build.sh
      secrets: [JWT_PRIVATE_KEY]
environments:
  production: {}       # the server in PRODUCTION_CONNECTION, the secrets in CI

See several apps on one server for the shared network, and backups for the database.