# Dockflow - Complete Documentation

> A powerful deployment framework that simplifies Docker deployments to remote servers using Docker Swarm.

---

# Getting Started

Dockflow deploys to a single server or a multi-node cluster — same workflow. All you need to get started is one Linux server.

  
  

## Setup Your Server

You need a Debian/Ubuntu server with SSH access (root or sudo user).

  

## Create Your Project

This generates the following structure at the root of your project:

    
    
  

- **`config.yml`** — Project name, build strategy, health checks ([reference](/configuration))
- **`servers.yml`** — Servers and environment variables ([reference](/configuration/servers))
- **`docker/`** — Docker Compose stack and Dockerfiles

## Deploy

  
  

    

      
    

    ### Repository secrets

    Add the connection string generated during setup to your CI/CD secrets:

---

# Configuration

Start with your project configuration, then define your servers and Docker Compose stack. The remaining topics are optional and can be explored as needed.

---

# Connection Configuration

See the [Servers & Connections](/configuration/servers) page for:
- [Connection strings](/configuration/servers#ci-secrets)
- [Individual CI secrets](/configuration/servers#ci-secrets)
- [Secret naming conventions](/configuration/servers#ci-secrets)
- [Priority resolution](/configuration/servers#variable-priority)

---

# Servers Configuration

The `servers.yml` file defines your server topology (roles, tags) and environment variables. Connection credentials are provided separately via **connection strings** generated by `dockflow setup`.

## Architecture

Dockflow uses **Docker Swarm** for orchestration. Each environment has one **manager** that receives deployments and optional **workers** that run distributed containers.

## Basic Structure

This defines a single server named `main_server` with the `manager` role. Connection details (host, SSH key) come from secrets — not from this file.

## Secrets

Dockflow needs SSH credentials to connect to your servers. The recommended approach is **connection strings**, generated automatically by `dockflow setup`.

      
    

    
  
  

### Variable Overrides

Override any environment variable via secrets:

## Server Fields

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `role` | No | `manager` | Node role: `manager` or `worker` |
| `tags` | Yes | - | Environment tags (e.g., `[production]`) |
| `env` | No | - | Server-specific environment variables |
| `host` | No | From connection string | Override host (rarely needed) |
| `user` | No | `defaults.user` | Override SSH user |
| `port` | No | `defaults.port` | Override SSH port |

### Examples

  

## Cluster Setup

Before your first multi-node deployment, initialize the Swarm cluster:

## Environment Variables

Define variables that are inherited based on tags:

### Variable Priority

Variables are resolved from lowest to highest priority. A higher-priority source always overrides a lower one:

## Jinja2 Templating

Values in `servers.yml` support Jinja2 templating:

Available variables:

| Variable | Description |
|----------|-------------|
| `}` | From config.yml |
| `}` | Current environment being deployed |
| `}` | Deployment version |
| `}` | Current server name |
| `}` | Current server host |
| `}` | Current server role (manager/worker) |

---

**Next:** [Docker Compose](/configuration/docker-compose) — define your application services, networks, and volumes.

---

# Environment Variables

See the [Servers & Connections](/configuration/servers) page for:
- [Defining variables per environment](/configuration/servers#environment-variables)
- [Variable priority](/configuration/servers#variable-priority)
- [CI secret overrides](/configuration/servers#variable-secrets)
- [Jinja2 templating](/configuration/servers#jinja2-templating)

---

# Docker Compose

Dockflow uses a standard `docker-compose.yml` file located at `.dockflow/docker/docker-compose.yml`. This file defines your application services, networks, and volumes.

## Basic Structure

The `build` section tells Dockflow how to build the image. The `context` is relative to the compose file location (`.dockflow/docker/`), so `../..` points to the project root.

## Environment Variables

Environment variables can come from multiple sources:

- **`servers.yml`** — defined per-environment or per-server (see [Servers & Connections](/configuration/servers))
- **CI secrets** — override `servers.yml` values
- **Jinja2 templating** — all files in `.dockflow/` are automatically processed with Jinja2

## Automatic Image Tagging

Dockflow automatically appends the environment and version to image names for isolation:

When a Docker registry is configured, the registry URL is also prepended:

This behavior can be disabled with `image_auto_tag: false` in [config.yml](/configuration/config-file).

## Deploy Configuration

The `deploy` section controls how Docker Swarm manages your services. Dockflow injects sensible defaults, so you only need to specify what you want to override.

### Default Values

Dockflow automatically injects these deploy settings for application services:

| Setting | Default |
|---------|---------|
| `update_config.parallelism` | 1 |
| `update_config.delay` | 10s |
| `update_config.failure_action` | rollback |
| `update_config.monitor` | 30s |
| `update_config.order` | start-first |
| `update_config.max_failure_ratio` | 0 |
| `rollback_config.parallelism` | 1 |
| `rollback_config.delay` | 5s |
| `rollback_config.monitor` | 15s |
| `rollback_config.order` | start-first |

Your compose file values always take priority over these defaults.

### Replicas and Resources

### Custom Update Strategy

## Health Checks

Docker health checks let Swarm verify that containers are actually working:

## Volumes

## Networks

Dockflow automatically creates external networks and volumes before deploying the stack.

## Placement Constraints

For multi-host deployments, you can control which nodes run each service:

See [Multi-Host Deployment](/configuration/multi-host) for details on configuring a multi-node cluster.

## Multi-Service Example

## Environment Isolation

Dockflow ensures complete isolation between environments (production, staging, etc.) through:

1. **Image names** — automatically tagged with environment and version (`my-app-production:1.0.0`)
2. **Stack names** — each environment gets its own Swarm stack
3. **Networks and volumes** — automatically prefixed with the stack name by Docker Swarm

---

**Next:** [Build Strategy](/configuration/build-strategy) — choose how to build and transfer Docker images.

---

# Accessories

Accessories are **stateful services** (databases, caches, message queues, etc.) that have a separate lifecycle from your main application. They are deployed once and remain untouched during regular app deployments.

## Why Accessories?

**Solution**: Accessories are deployed as a separate Docker Swarm stack. Your app can be deployed 100 times without touching the database.

## Configuration

Create a file at `.dockflow/docker/accessories.yml` using standard Docker Compose format:

## Automatic Swarm Configuration

Dockflow automatically injects a minimal Swarm configuration for each accessory service:

This ensures:
- **Single replica** by default (appropriate for stateful services)
- **Automatic restart** on failure with backoff
- **No rolling updates** (you control when to update databases)

You can override any of these in your `accessories.yml`.

## Deployment

Dockflow uses **hash-based change detection** for accessories. This means:

- First deployment → accessories are automatically deployed
- `accessories.yml` changed → accessories are automatically redeployed
- No changes → accessories are skipped (fast)

### Automatic Deployment (Default)

### Force Redeploy Accessories

### Skip Accessories Check

## Management Commands

All accessories commands use SSH to interact with the running services.

### List Accessories

Shows all accessories services with their status and replicas.

### View Logs

### Execute Commands

### Restart Services

### Stop Services

### Remove Accessories

## Best Practices

### 1. Always Use Named Volumes

### 2. Pin Image Versions

### 3. Configure Health Checks

### 4. Constrain to Manager Node (Optional)

For single-node deployments, this ensures data stays on the same node:

## Connecting Your App

Your main application can connect to accessories using Docker's internal DNS:

---

# Build Strategy

Dockflow supports different strategies for building and transferring Docker images to your servers.

## Strategies Overview

| Strategy | Build Location | Transfer Method | Best For |
|----------|---------------|-----------------|----------|
| Local (default) | CI/CD runner | SSH streaming | Single-node, small clusters |
| Local + Registry | CI/CD runner | Docker registry | Large multi-node clusters |
| Remote | Target server | None (built in place) | Large contexts, slow networks |

## Local Build (Default)

Images are built in your CI/CD pipeline and transferred to the server via SSH. No additional configuration required.

**How it works:**
1. Dockflow parses `docker-compose.yml` to extract build commands
2. Images are built locally (in parallel if multiple services)
3. Images are streamed to all Swarm nodes via SSH:
   ```
   docker save IMAGE | gzip -1 | ssh user@host "gunzip | docker load"
   ```

This is the simplest strategy and works for both single-node deployments and multi-node clusters. For larger clusters with many nodes or heavy images, consider using a [registry](/configuration/registry) instead.

## Registry Build

For larger multi-node Swarm clusters, use a Docker registry so all nodes can pull images independently. This avoids streaming large images over SSH to each node individually.

**How it works:**
1. Images are built locally (same as default)
2. Images are pushed to your configured registry
3. During `docker stack deploy`, each Swarm node pulls the image from the registry

See [Docker Registry](/configuration/registry) for full configuration (GHCR, GitLab, Docker Hub, self-hosted).

**When to use:**
- Large multi-node clusters where SSH streaming becomes a bottleneck
- When you want image versioning in a registry
- CI/CD pipelines with native registry support

## Remote Build

Build images directly on the server instead of transferring them:

**How it works:**
1. Dockflow clones your repository on the target server (supports Git token authentication)
2. Images are built directly on the server
3. No image transfer needed — images are already where they need to be

For private repositories, add a `GIT_TOKEN` secret to your CI/CD environment. Dockflow auto-constructs authenticated URLs for GitHub and GitLab.

**When to use:**
- Large build contexts that would be slow to transfer
- Slow network connections between CI/CD and server
- When the server has more build resources than your CI runner

## Trade-Offs

| | Local | Local + Registry | Remote |
|---|---|---|---|
| **Setup complexity** | None | Registry config needed | Git access on server |
| **Network usage** | SSH stream per node | Single push, nodes pull | Git clone only |
| **Build cache** | Full local cache | Full local cache | Pruned between deploys |
| **Multi-node** | Streaming to each node | Native Swarm pull | Streaming to workers |
| **CI resources** | Needs Docker on runner | Needs Docker on runner | Minimal CI resources |
| **Private repos** | N/A | N/A | Needs `GIT_TOKEN` |

## Build-Only Mode

Use `dockflow build` to build images without deploying:

This is useful for validating builds in CI before deploying, or for pre-building images.

## Docker Cache

Docker caches image layers by default. When nothing changes in your source code or Dockerfile, subsequent builds reuse cached layers and complete in seconds.

To maximize cache efficiency:
- Order Dockerfile instructions from least to most frequently changing
- Copy dependency files (`package.json`, `requirements.txt`) before source code
- Use multi-stage builds to separate build and runtime dependencies

---

**Next:** [Deployment](/deployment) — understand what happens when you deploy.

---

# Docker Registry

A Docker registry stores your images centrally so Swarm nodes can pull them independently.

## When to Use

- **Single node**: Not required. Images are transferred via SSH.
- **Multi-node Swarm**: Recommended for large clusters. Without a registry, Dockflow transfers images to each node via SSH (`docker save | ssh | docker load`), which works well for small clusters but becomes slower as the number of nodes or image size grows.

## Configuration

Add the following to `.dockflow/config.yml`:

  
  
  
  
  
  

## Configuration Reference

| Field | Description |
|-------|-------------|
| `enabled` | Set to `true` to push images to the registry |
| `url` | Registry hostname |
| `namespace` | Organization or username prefix for images |
| `auth_method` | `token` or `basic` |
| `username` | Registry username |
| `password` / `token` | Credentials (use Jinja2 syntax for secrets) |

## Image Tagging

By default, images are tagged with the deployment version. You can add extra tags that point to the same image:

**Example:** Deploying version `1.2.0` to `production` produces:

Available variables: ``, ``, ``, ``

## Troubleshooting

**Authentication failed**: Test credentials manually with `docker login`.

**Push denied**: Verify write access to the namespace.

**Workers cannot pull**: Ensure all Swarm nodes can reach the registry. For private registries, authenticate on each node.

---

# Templates

Dockflow renders files with Jinja2 templating before deployment, injecting environment-specific values into your configuration.

## Automatic Rendering

All files inside `.dockflow/` are **automatically rendered** with Jinja2 during deployment. No configuration needed.

## Custom Templates

For files **outside** `.dockflow/`, declare them in `.dockflow/config.yml`. Paths are relative to the project root:

These files are rendered in-place. To output to a different location, use the extended format:

## Available Variables

### Basic Variables

| Variable | Description | Example |
|----------|-------------|--------|
| `}` | Target environment | `production` |
| `}` | Deployment version | `1.2.3` |
| `}` | Git branch name | `main` |
| `}` | Current server name | `manager_1` |
| `}` | Project name from config | `my-app` |

### Current Server (`}`)

The `current` object contains information about the server being deployed to:

| Variable | Description | Example |
|----------|-------------|--------|
| `}` | Server name from servers.yml | `manager_1` |
| `}` | Server IP or hostname | `192.168.1.10` |
| `}` | SSH port | `22` |
| `}` | SSH user | `dockflow` |
| `}` | Server role | `manager` or `worker` |
| `}` | Server tags | `['production']` |
| `}` | Environment variable (lowercase key) | `my-value` |

### Config (`}`)

All values from your `config.yml`:

### All Servers (`}`)

All servers in the current environment, keyed by name. Each server has the same properties as `current`.

### Cluster Metadata (`}`)

| Variable | Description | Example |
|----------|-------------|--------|
| `}` | Total number of nodes | `5` |
| `}` | Number of managers | `1` |
| `}` | Number of workers | `4` |
| `}` | List of manager IPs | `['192.168.1.10']` |
| `}` | List of worker IPs | `['192.168.1.11', '192.168.1.12']` |

## Jinja2 Syntax

### Conditionals

### Default values

### Loops

## Execution Order

Templates are rendered early in the deployment process:

1. Load configuration (`config.yml`, `servers.yml`)
2. **Render all files in `.dockflow/`** (docker-compose, Dockerfiles, etc.)
3. **Render custom templates** from `config.yml`
4. Auto-tag Docker images in `docker-compose.yml` (if `image_auto_tag` is enabled)
5. Build Docker images
6. Deploy to swarm

## Examples

These are example template files you could create in your project.

### Application config (e.g. `config/application.yml`)

### Nginx reverse proxy (e.g. `nginx/myapp.conf.j2`)

### Init script (e.g. `scripts/init.sh`)

### PostgreSQL access control (e.g. `config/pg_hba.conf.j2`)

---

# Hooks

Hooks allow you to run custom scripts at specific points during deployment.

## Available Hooks

| Hook | Location | Timing |
|------|----------|--------|
| `pre-build` | CI runner | Before Docker images are built |
| `post-build` | CI runner | After Docker images are built |
| `pre-deploy` | Server | Before Swarm stack deployment |
| `post-deploy` | Server | After successful deployment |

## Setup

Create shell scripts in `.dockflow/hooks/`:

  

All hooks are optional. If a hook file doesn't exist, it is skipped.

## Jinja2 Templating

Hooks are rendered with Jinja2 before execution. You can use any Ansible variable:

## Examples

### Pre-build: Generate assets

### Post-build: Security scan

### Pre-deploy: Database backup

### Post-deploy: Notify team

## Configuration

Hooks are enabled by default. Configure in `.dockflow/config.yml`:

---

# Multi-Node Deployment

Deploy your application across multiple servers using Docker Swarm with managers and workers.

## Swarm Architecture

- **Managers**: Receive deployments and orchestrate the cluster
- **Workers**: Run containers distributed by managers
- **Multi-manager**: For high availability (tolerates manager failures)

## Basic Configuration

Each server needs a connection string in your secrets:

## Multi-Manager for High Availability

For production environments, configure multiple managers for failover:

## Automatic Failover

When deploying with multiple managers, Dockflow automatically:

1. Checks each manager's status via SSH
2. Finds the Swarm leader (or any reachable manager)
3. Falls back to the next available manager if one is down

Example output with failover:

## How Deployment Works

1. **Deploy targets the manager** — Dockflow connects only to the active manager
2. **Swarm distributes workloads** — Containers are scheduled across all nodes
3. **Images are transferred to workers** — Via SSH streaming or [registry](/configuration/registry)

## Server-Specific Environment Variables

Override variables for specific servers:

---

# 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

## `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.

The stack name is derived as `-`. Releases are stored at:

## Options

### `image_auto_tag`
**Default:** `true`

Appends `-:` 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](/configuration/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 Docker images from failed deployments immediately.

## 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 from the host, configured below.

### `enabled`
**Default:** `true`

Enable or disable post-deployment health checks.

### `startup_delay`
**Default:** `15` (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:

| Value | Behavior |
|-------|----------|
| `"fail"` | Mark deployment as failed |
| `"rollback"` | Rollback to the previous stack |
| `"notify"` | Log a warning but continue |
| `"ignore"` | Skip health check failures |

### `endpoints`

List of HTTP endpoints to check after deployment:

| Field | Description |
|-------|-------------|
| `name` | Descriptive label |
| `url` | URL to check (supports Jinja2: `}`) |
| `expected_status` | Expected HTTP status code |
| `timeout` | Request timeout in seconds |
| `retries` | Number of retry attempts |

## 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/.log`:

---

**Next:** [Servers & Connections](/configuration/servers) — define your servers, environment variables, and CI secrets.

---

# Deployment

When you run `dockflow deploy`, Dockflow builds your Docker images, transfers them to your server, deploys the stack via Docker Swarm, and verifies that services are healthy. If health checks fail, it rolls back automatically.

## Triggering a Deployment

  
  

The environment name must match a server tag in your [`servers.yml`](/configuration/servers).

## Deployment Process

## Release Management

Dockflow organizes releases on your server:

The `current` symlink points to the active release. By default, Dockflow keeps the last 3 releases (configurable via [`keep_releases`](/configuration/config-file#keep_releases)).

## Health Checks

### Swarm Health Checks

Define health checks in your `docker-compose.yml`:

Swarm monitors these checks and triggers automatic rollback if containers become unhealthy.

### External Health Checks

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

See [Health Checks configuration](/configuration/config-file#health-checks) for all options.

## Rolling Updates

Dockflow injects safe defaults for zero-downtime 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 | — |

### Customizing

Override any setting in your `docker-compose.yml`:

### 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

## Troubleshooting

### Deployment Stuck

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:

### Images Not Found

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

---

**Next:** [CLI Reference](/cli) — all available commands and options.

---

# CLI Commands

Dockflow provides a comprehensive CLI for managing deployments and interacting with running services.

## Installation

  

The script detects your platform and architecture, downloads the binary, and adds it to your PATH.

### Available Binaries

| Binary | Platform | Architecture |
|--------|----------|-------------|
| `dockflow-linux-x64` | Linux | x86_64 |
| `dockflow-linux-arm64` | Linux | ARM64 |
| `dockflow-macos-x64` | macOS | Intel |
| `dockflow-macos-arm64` | macOS | Apple Silicon |
| `dockflow-windows-x64.exe` | Windows | x86_64 |

## Global Options

These options are available on all commands:

| Option | Description |
|--------|-------------|
| `--no-color` | Disable colored output |
| `--verbose` | Enable verbose output |
| `-v, --version` | Show CLI version |

## Connection Configuration

App commands require connection strings configured as CI secrets or in `.env.dockflow` for local development:

The connection string is generated by `dockflow setup` and contains:
- `host`: Server IP or hostname
- `port`: SSH port
- `user`: Deployment user
- `privateKey`: SSH private key
- `password`: User password (optional)

## Core Commands

### Deploy

Deploy the application to the specified environment.

| Option | Description |
|--------|-------------|
| `--services ` | Comma-separated list of services to deploy |
| `--skip-build` | Skip the build phase |
| `--force` | Force deployment even if locked |
| `--skip-docker-install` | Skip Docker installation on target |
| `--accessories` | Deploy only accessories (force redeploy) |
| `--all` | Deploy app + force redeploy accessories |
| `--skip-accessories` | Skip accessories check entirely |
| `--no-failover` | Disable multi-manager failover (use first manager only) |
| `--dry-run` | Show what would be deployed without executing |
| `--debug` | Enable debug output |

### Build

Build Docker images locally without deploying.

| Option | Description |
|--------|-------------|
| `--services ` | Comma-separated list of services to build |
| `--push` | Push images to registry after build |
| `--skip-hooks` | Skip pre-build and post-build hooks |
| `--debug` | Enable debug output |

### Init

Initialize the `.dockflow/` folder structure with configuration files and CI/CD setup.

### Config

Display and validate project configuration.

| Subcommand | Description |
|------------|-------------|
| `show` (default) | Display current configuration |
| `validate` (alias: `check`) | Validate configuration files against schemas |
| `path` | Show configuration directory path |

| Option | Applies to | Description |
|--------|-----------|-------------|
| `--json` | show, validate | Output as JSON |
| `--verbose` | validate | Show detailed validation output |

### UI

Launch the Dockflow WebUI dashboard for visual management of services, topology, and logs.

| Option | Description |
|--------|-------------|
| `-p, --port ` | Port to listen on (default: 4200) |
| `--no-open` | Do not open browser automatically |

## App Commands

These commands interact with deployed services via SSH. Most accept `-s, --server ` to target a specific server (defaults to the first server for the environment).

### Logs

View logs from running services.

| Option | Description |
|--------|-------------|
| `-f, --follow` | Follow log output |
| `-n, --tail ` | Number of lines to show (default: 100) |
| `-t, --timestamps` | Show timestamps |
| `--since ` | Show logs since timestamp (e.g., `1h`, `2024-01-01`) |
| `-s, --server ` | Target server |

### Exec

Execute a command inside a running container (default: bash).

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |
| `-u, --user ` | Run as specified user |
| `-w, --workdir ` | Working directory inside container |

### Bash

Open an interactive shell in a container. Alias: `shell`.

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |
| `--sh` | Use sh instead of bash |

### Restart

Force restart services (rolling update).

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |

### Stop

Stop and remove the entire stack. Prompts for confirmation.

| Option | Description |
|--------|-------------|
| `-y, --yes` | Skip confirmation |
| `-s, --server ` | Target server |

### Scale

Scale a service to a specified number of replicas.

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |

### Rollback

Rollback a service to its previous version.

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |

### PS

List running containers for the stack.

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |
| `--tasks` | Show tasks instead of containers |

### Version

Show the currently deployed application version.

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |
| `--json` | Output as JSON |

### Audit

Show deployment audit log (who deployed what and when).

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |
| `-n, --lines ` | Number of entries to show (default: 20) |
| `--all` | Show all entries |
| `--json` | Output as JSON |

### Metrics

Show deployment metrics and statistics.

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |
| `--history` | Show deployment history |
| `-n, --lines ` | Number of history entries (default: 20) |
| `--json` | Output as JSON |
| `--prune` | Remove old metrics (keep last 1000) |

### Diagnose

Diagnose deployment issues and show why containers may not be starting.

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |
| `-v, --verbose` | Show all diagnostic details |

### Details

Show stack overview with services, replicas, and resource usage.

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |

### SSH

Open an interactive SSH session or execute a command on the server.

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |

### Prune

Remove unused Docker resources from the server.

| Option | Description |
|--------|-------------|
| `-a, --all` | Remove all unused images, not just dangling |
| `--images` | Prune images only |
| `--containers` | Prune containers only |
| `--volumes` | Prune volumes only |
| `--networks` | Prune networks only |
| `-y, --yes` | Skip confirmation |
| `-s, --server ` | Target server |

## List Commands

### List Environments

List available environments and their servers. Aliases: `envs`, `environments`.

| Option | Description |
|--------|-------------|
| `--json` | Output as JSON |

### List Services

List services in a deployed stack. Alias: `svc`.

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |
| `-t, --tasks` | Show individual tasks for each service |
| `--json` | Output as JSON |

### List Images

Show application images on the server.

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |
| `-a, --all` | Show all images, not just app images |

## Lock Commands

Manage deployment locks to prevent concurrent deployments.

### Acquire Lock

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |
| `-m, --message ` | Lock reason |
| `--force` | Force acquire even if already locked |

### Lock Status

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |

### Release Lock

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |
| `--force` | Force release without confirmation |

## Accessories Commands

Manage stateful services (databases, caches) with a separate lifecycle. Alias: `acc`. See [Accessories Configuration](/configuration/accessories) for setup.

### Deploy Accessories

| Option | Description |
|--------|-------------|
| `--skip-docker-install` | Skip Docker installation |
| `--debug` | Enable debug output |

### List Accessories

| Option | Description |
|--------|-------------|
| `-s, --server ` | Target server |
| `--json` | Output as JSON |

### Accessories Logs

| Option | Description |
|--------|-------------|
| `-f, --follow` | Follow log output |
| `-n, --tail ` | Number of lines (default: 100) |
| `--since ` | Show logs since timestamp |
| `--timestamps` | Show timestamps |
| `--raw` | Raw output without formatting |
| `-s, --server ` | Target server |

### Accessories Exec

Execute a command in an accessory container (default: sh).

| Option | Description |
|--------|-------------|
| `-u, --user ` | Run as specified user |
| `--workdir ` | Working directory |
| `-s, --server ` | Target server |

### Restart Accessories

| Option | Description |
|--------|-------------|
| `--force` | Force restart even if updating |
| `-s, --server ` | Target server |

### Stop Accessories

Scale accessories to 0 replicas (keeps volumes).

| Option | Description |
|--------|-------------|
| `-y, --yes` | Skip confirmation |
| `-s, --server ` | Target server |

### Remove Accessories

Remove the accessories stack entirely.

| Option | Description |
|--------|-------------|
| `-v, --volumes` | Also remove volumes (DESTRUCTIVE) |
| `-y, --yes` | Skip confirmation |
| `-s, --server ` | Target server |

## Setup Commands

Configure servers for deployment. Must be run on a Linux host or via `setup remote`.

### Interactive Setup

Run the interactive setup wizard. On Windows/macOS, prompts to connect to a Linux server via SSH.

### Remote Setup

Run setup on a remote Linux server from any platform.

| Option | Description |
|--------|-------------|
| `--host ` | Remote server IP or hostname |
| `--port ` | SSH port (default: 22) |
| `--user ` | SSH username |
| `--password ` | SSH password |
| `--key ` | Path to SSH private key |
| `--connection ` | Use existing Dockflow connection string |

### Non-Interactive Setup

Configure a server without prompts (Linux only, must run on target host).

| Option | Description |
|--------|-------------|
| `--host ` | Public IP/hostname for connection string |
| `--port ` | SSH port (default: 22) |
| `--user ` | Deployment username |
| `--password ` | Password for new user or sudo |
| `--ssh-key ` | Path to existing SSH private key |
| `--generate-key` | Generate new SSH key |
| `--skip-docker-install` | Skip Docker installation |
| `--portainer` | Install Portainer |
| `--portainer-port ` | Portainer HTTP port (default: 9000) |
| `--portainer-password ` | Portainer admin password |
| `--portainer-domain ` | Portainer domain name |
| `-y, --yes` | Skip confirmations |

### Initialize Swarm

Initialize a Docker Swarm cluster for an environment. Joins all servers configured in `servers.yml` into the Swarm.

### Check Dependencies

Verify all required dependencies are installed.

### Get Connection String

Display connection string for an existing deployment user.

| Option | Description |
|--------|-------------|
| `--host ` | Server IP/hostname |
| `--port ` | SSH port (default: 22) |
| `--user ` | Deployment username |
| `--key ` | Path to SSH private key |

## Requirements

- `.env.dockflow` with connection strings (or CI secrets)
- `.dockflow/config.yml` with `project_name`

**For setup commands (on target Linux host):**
- Ansible (`ansible`, `ansible-playbook`)
- SSH (`ssh`, `ssh-keygen`)

## Full Workflow Example

---

# Advanced Usage

Operational patterns for managing deployments beyond the basics.

## Deployment Locks

Prevent concurrent deployments with manual locks:

The `dockflow deploy --force` flag overrides locks when needed.

## Selective Deployment

Deploy specific services without affecting others:

Skip the build phase to redeploy with existing images:

Preview what a deployment would do without executing:

## Debug Workflow

When something goes wrong:

Enable verbose Ansible output during deploy:

## History Replication

Deployment history (audit log and metrics) is automatically replicated to **all cluster nodes** (managers and workers) after each deployment. This ensures:

- No data loss if a manager goes down
- Seamless history access after worker-to-manager promotion
- No fragmented history when manager failover occurs

History is read with automatic fallback: if the primary manager is unreachable, Dockflow tries other managers, then workers.

### Manual Sync

If a node was offline during a deployment or a new node was added to the cluster, manually sync the full history:

This reads history from all reachable nodes, merges and deduplicates entries, then writes the complete dataset back to every node.

---

# AI Integration

Dockflow provides first-class support for AI assistants through the [llms.txt standard](https://llmstxt.org/) and a dedicated [MCP server](https://modelcontextprotocol.io/).

## llms.txt

The documentation is available in machine-readable format following the llms.txt standard:

| File | Description | URL |
|------|-------------|-----|
| `llms.txt` | Concise index with links and descriptions for each page | [`/llms.txt`](/llms.txt) |
| `llms-full.txt` | Complete documentation concatenated into a single file | [`/llms-full.txt`](/llms-full.txt) |

These files are generated automatically at build time from the documentation sources.

## MCP Server

The `@dockflow-tools/mcp` package provides a [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes Dockflow documentation as tools for AI assistants.

### Installation

  
  
  

### Available Tools

| Tool | Description |
|------|-------------|
| `list_pages` | List all available documentation pages with descriptions |
| `search_docs` | Search documentation for a specific topic or keyword |
| `get_page` | Get the full content of a specific documentation page |

### Example Usage

Once configured, you can ask your AI assistant questions like:

- *"How do I configure multi-host deployment with Dockflow?"*
- *"What are the available CLI commands?"*
- *"Show me the accessories configuration reference"*

The MCP server fetches documentation from the live site and caches it in memory for fast responses.

---

# Examples

Complete configuration examples for common deployment scenarios.

## Minimal Setup

A single Node.js service deployed to one server.

### Project Structure

    
  

### config.yml

### servers.yml

### docker-compose.yml

### Dockerfile

### Deploy

## Full-Stack with Accessories

A frontend + backend application with PostgreSQL and Redis as accessories.

### Project Structure

    
    

### config.yml

### servers.yml

### docker-compose.yml

### accessories.yml

### Deploy

## Multi-Host with Registry

A high-availability setup with multiple servers and a Docker registry.

### servers.yml

### config.yml

### docker-compose.yml

### CI secrets

### Setup

## Custom Templates

Using Jinja2 templates to generate Nginx configuration per-server:

### config.yml

### nginx/app.conf.j2

See [Templates](/configuration/templates) for the full templating reference.

## Projects Using Dockflow

| Project | Description | Link |
|---------|-------------|------|
| **MohistMC Frontend** | React app with Nginx | [View](https://github.com/MohistMC/mohistmc-frontend) |
| **MohistMC Backend** | Spring Boot API | [View](https://github.com/MohistMC/mohistmc-backend) |
| **Maven Repository** | Maven registry server | [View](https://github.com/MohistMC/maven) |
| **Personal Website** | Portfolio site | [View](https://github.com/Shawiizz/shawiizz.dev) |