Deployment

When you run dockflow deploy, Dockflow builds your images, transfers them to your server, deploys the stack, and verifies that services are healthy. The process adapts automatically based on your orchestrator setting (Swarm or k3s).

Triggering a Deployment

CLI


dockflow deploy production 1.0.0

Tag (CI/CD)

Push a git tag to trigger a deployment. The CLI auto-detects the environment from the tag suffix:


git tag 1.0.0              # → deploys to production
git tag 1.0.0-staging      # → deploys to staging
git push origin --tags

The tag name is used as the version. A tag without a suffix (e.g., 1.0.0) deploys to production. A tag ending with -<env> (e.g., 1.0.0-staging) deploys to that environment.

Branch (CI/CD)

Push to a branch to trigger a build or deploy. The CLI auto-detects the branch and generates a version from <branch>-<commit-sha>:


git push origin main       # → builds or deploys to production as main-abc12345

The environment name must match a server tag in your servers.yml.

Deployment Process

Image Transfer

Dockflow transfers your images to the server via SSH. The method depends on your orchestrator and container engine:

Swarm (Docker)


docker save image:tag | gzip -1 | ssh user@host "gunzip | docker load"

Swarm (Podman)


podman save image:tag | gzip -1 | ssh user@host "gunzip | podman load"

k3s


docker save image:tag | gzip -1 | ssh user@host "gunzip | sudo k3s ctr -n k8s.io images import -"

k3s always uses containerd for image import, regardless of the build engine.

No external registry required. For multi-node Swarm clusters, images are streamed to each node. You can optionally configure a Docker registry for faster transfers.

Stack Deployment

Swarm

Your application is deployed as a Swarm stack:


docker stack deploy -c docker-compose.yml my-app-production

Each deployment creates a new release directory on the server.

Health Verification

After deployment, Dockflow verifies:

Internal checks: Swarm reports services as healthy / k3s pods reach Running state (no CrashLoopBackOff)
The correct image version is running
External health check endpoints respond (if configured)

Rollback on Failure

If health checks fail, Dockflow:

Detects the rollback via Swarm status
Waits for the previous version to stabilize
Cleans up the failed release
Reports the deployment as failed

Release Management

Dockflow organizes releases on your server:


/var/lib/dockflow/stacks/my-app-production/
├── 1.0.0/
│   └── docker-compose.yml
├── 1.0.1/
│   └── docker-compose.yml
├── 1.0.2/
│   └── docker-compose.yml
└── current -> 1.0.2/

The current symlink points to the active release. By default, Dockflow keeps the last 3 releases (configurable via keep_releases).

Health Checks

Container Health Checks

Define health checks in your docker-compose.yml:


services:
  app:
    image: my-app
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 30s

Swarm: Docker monitors these checks natively and triggers automatic rollback if containers become unhealthy.
k3s: Dockflow converts them to Kubernetes livenessProbe and readinessProbe automatically. No manual K8s YAML needed.

External Health Checks

Configure additional HTTP checks in .dockflow/config.yml:


health_checks:
  enabled: true
  startup_delay: 15
  on_failure: rollback
  endpoints:
    - name: "API"
      url: "http://localhost:3000/health"
      expected_status: 200
      timeout: 30
      retries: 3

See Health Checks configuration for all options.

Rolling Updates

Rolling update settings apply to Swarm only. For k3s, Kubernetes handles rolling updates via its own Deployment strategy (default: RollingUpdate with 25% maxSurge / 25% maxUnavailable).

Dockflow injects safe defaults for zero-downtime Swarm deployments. These are only applied if not already defined in your docker-compose.yml.

Default Settings

Setting	Update	Rollback
`parallelism`	1	1
`delay`	10s	5s
`failure_action`	rollback	—
`monitor`	30s	15s
`order`	start-first	start-first
`max_failure_ratio`	0	—

Your docker-compose.yml values always take precedence. Dockflow only fills in missing fields.

Customizing

Override any setting in your docker-compose.yml:


services:
  app:
    deploy:
      replicas: 3
      update_config:
        parallelism: 2
        delay: 5s
        failure_action: pause
        monitor: 60s
        order: stop-first
      rollback_config:
        parallelism: 2
        delay: 3s

Update Order

start-first (default): New container starts before the old one stops. Zero downtime, but requires brief extra resources.
stop-first: Old container stops before the new one starts. Less resources but causes brief downtime.

For zero-downtime deployments, use start-first with at least 2 replicas.

Manual Operations

Swarm


# View stack status
docker stack services my-app-production
 
# View service logs
docker service logs my-app-production_app
 
# Force redeployment
docker service update --force my-app-production_app
 
# Manual rollback
docker service rollback my-app-production_app
 
# Remove stack
docker stack rm my-app-production

Troubleshooting

Deployment Stuck

Swarm


docker service ps my-app-production_app --no-trunc

Look for error messages in the task output.

Rollback Loop

If services keep rolling back, the issue is usually in your container health check. Verify the health check command works:


# Swarm
docker exec <container_id> curl -f http://localhost:3000/health
 
# k3s
kubectl exec -n dockflow-my-app-production <pod_name> -- curl -f http://localhost:3000/health

Images Not Found

If the orchestrator cannot find images after a rollback, cleanup may have removed them. Redeploy:


dockflow deploy production 1.0.3

Next: CLI Reference — all available commands and options.