Project Configuration

The config.yml file defines your project identity, build options, health checks, and deployment behavior. This is the first file to configure in any Dockflow project.

Full Example

# .dockflow/config.yml
 
project_name: "my-app"
 
proxy:
  enabled: true
  email: [email protected]
  domains:
    production: my-app.example.com
    staging: staging.my-app.example.com
 
options:
  image_auto_tag: true
  enable_debug_logs: false
  remote_build: false
 
stack_management:
  keep_releases: 3
  cleanup_on_failure: true
 
lock:
  stale_threshold_minutes: 30
 
health_checks:
  enabled: true
  startup_delay: 15
  on_failure: "rollback"
  wait_for_internal: true
  endpoints:
    - name: "Main Application"
      url: "http://localhost:{{ current.env.app_port }}/health"
      remote: true
      expected_status: 200
      timeout: 30
      retries: 3

project_name (required)

Unique identifier for your project. Used as the Docker Swarm stack name prefix and release directory name.

Format: lowercase letters, numbers, and hyphens only.

project_name: "my-app"

The stack name is derived as {project_name}-{env}. Releases are stored at:

/var/lib/dockflow/stacks/my-app-production/
  1/
  2/
  3/
  current -> 3/

Options

image_auto_tag

Default: true

Appends -{env}:{version} to image names for environment isolation:

• my-app → my-app-production:1.0.0
• backend:latest → backend-staging:2.1.0

Set to false to keep image names as defined in docker-compose.yml.

enable_debug_logs

Default: false

Enables verbose logging for debugging deployment issues.

remote_build

Default: false

Build Docker images on the server instead of in the CI/CD pipeline. See Build Strategy for details.

Stack Management

keep_releases

Default: 3

Number of previous releases to retain on the server. Enables quick rollback and automatic cleanup of old releases and images.

cleanup_on_failure

Default: true

Remove images built for a failed deployment from all cluster nodes immediately after failure. Has no effect when a registry is used — images pushed to a registry are not deleted.

Health Checks

Two layers of health verification:

1. Swarm internal — Docker monitors container healthchecks defined in docker-compose.yml and rolls back automatically on failure.
2. Dockflow external — HTTP endpoint checks after convergence, configurable below. Checks run locally by default; set remote: true to run them via SSH on the manager node instead.

enabled

Default: true

Enable or disable post-deployment health checks.

startup_delay

Default: 10 (seconds)

Time to wait after deployment before running external health checks.

wait_for_internal

Default: true

Wait for Swarm internal healthchecks to pass before running external checks.

on_failure

Action when external health checks fail:

endpoints

List of HTTP endpoints to check after deployment:

endpoints:
  # Local check — the CLI machine must be able to reach this URL
  - name: "Public API"
    url: "https://api.example.com/health"
    expected_status: 200
    timeout: 30
    retries: 3
 
  # Remote check — curl runs on the manager via SSH
  - name: "Internal service"
    url: "http://localhost:{{ app_port }}/health"
    remote: true
    expected_status: 200
    retries: 5
    retry_delay: 3

Proxy

Automatic HTTPS routing via Traefik + Let’s Encrypt. See Automatic HTTPS Proxy for the full reference.

proxy:
  enabled: true
  email: [email protected]
  domains:
    production: my-app.example.com

Deploy Lock

stale_threshold_minutes

Default: 30

Dockflow prevents concurrent deployments to the same stack. Lock files are stored in /var/lib/dockflow/locks/ and expire after this threshold. Accepts values from 1 to 1440 (24 hours).

Audit Log

Every deployment is recorded at /var/lib/dockflow/audit/{stack-name}.log:

2024-01-15T10:30:00Z | DEPLOYED | 1.0.0 | user@ci-runner | success
2024-01-16T14:20:00Z | DEPLOYED | 1.0.1 | user@ci-runner | success

Next: Servers & Connections — define your servers, environment variables, and CI secrets.