Skip to Content
⚠️ Dockflow is currently under development. Bugs may occur. Please report any issues on GitHub.
Configurationdockflow.yml

dockflow.yml

dockflow.yml is a single-file alternative to the standard .dockflow/ layout. Instead of maintaining separate config.yml and servers.yml files inside a dedicated directory, you place one dockflow.yml at the project root alongside your docker-compose.yml.

This layout is designed for simple projects with a single server. For multi-environment setups, advanced templates, or shared server configs across repos, the standard .dockflow/ layout gives you more control.

Minimal example

# dockflow.yml
project_name: my-app
 
servers:
  main:
    host: 1.2.3.4
    tags: [production]
 
defaults:
  user: deploy
# docker-compose.yml (at project root)
services:
  app:
    image: my-app
    build: .
    ports:
      - "3000:3000"

That’s the entire configuration. No .dockflow/ directory, no subdirectories.

Project layout

my-project/
├── dockflow.yml         ← replaces .dockflow/config.yml + .dockflow/servers.yml
├── docker-compose.yml   ← replaces .dockflow/docker/docker-compose.yml
├── Dockerfile
└── src/

All options

dockflow.yml accepts every field from both config.yml and servers.yml — they share no overlapping keys, so the merge is flat.

From config.yml:

FieldTypeDescriptionDefault
project_namestringUnique project identifier (DNS-safe, required)—
orchestratorswarm | k3sDeployment backendswarm
container_enginedocker | podmanBuild engine (auto-detected if unset)auto
registryobjectDocker registry config—
optionsobjectremote_build, image_auto_tag, enable_debug_logs—
stack_managementobjectkeep_releases, cleanup_on_failure—
health_checksobjectEndpoint checks, timeouts, on-failure behavior—
hooksobjectpre-build, post-build, pre-deploy, post-deploy scripts—
lockobjectstale_threshold_minutes—
backupobjectBackup config for accessories and services—
templatesarrayNunjucks template files to render before deploy—
accessoriesobjectInline accessory service definitions—
proxyobjectTraefik + Let’s Encrypt configuration—
notificationsobjectWebhook notifications on deploy events—

From servers.yml:

FieldTypeDescriptionDefault
serversobjectServer definitions keyed by name (required)—
servers.<name>.hoststringServer hostname or IP—
servers.<name>.rolemanager | workerSwarm rolemanager
servers.<name>.tagsstring[]Environment tags, e.g. [production] (required)—
servers.<name>.userstringSSH user (overrides defaults.user)—
servers.<name>.portnumberSSH port (overrides defaults.port)—
servers.<name>.envobjectServer-specific environment variables—
defaults.userstringDefault SSH user for all serversdockflow
defaults.portnumberDefault SSH port for all servers22
envobjectEnvironment variables by tag (all, production, etc.)—

See Servers & Connections and Project Configuration for full documentation of each field.

How it works

Dockflow detects dockflow.yml

When you run any dockflow command, it traverses up from the current directory looking for dockflow.yml or .dockflow/. If dockflow.yml is found first, the flat layout is activated.

Config and servers are split internally

The file is parsed once and cached. The config fields are routed to the same logic that reads .dockflow/config.yml, and the server fields to the same logic that reads .dockflow/servers.yml. No code in the deploy pipeline changes.

docker-compose.yml is read from the project root

Instead of .dockflow/docker/docker-compose.yml, Dockflow looks for docker-compose.yml (or .yaml) at the project root. Build context paths in the compose file are relative to the project root, which is the standard Docker Compose behavior.

Caveats

If both dockflow.yml and .dockflow/ exist in the same directory, dockflow.yml takes priority.

  • Templates: the templates field resolves paths relative to the project root (same as the standard layout).
  • Accessories: place accessories.yml at the project root alongside dockflow.yml. If not found there, Dockflow falls back to .dockflow/docker/accessories.yml. You can also define accessories inline under the accessories key in dockflow.yml.
  • CI secrets: the {ENV}_{SERVER}_CONNECTION format works identically — host overrides apply regardless of the layout.

Full example

# dockflow.yml
project_name: my-app
 
servers:
  web:
    host: 1.2.3.4
    tags: [production]
 
defaults:
  user: deploy
  port: 22
 
env:
  production:
    APP_ENV: production
 
proxy:
  enabled: true
  email: [email protected]
  domains:
    production: my-app.example.com
 
health_checks:
  enabled: true
  endpoints:
    - url: https://my-app.example.com
      retries: 5
 
stack_management:
  keep_releases: 3

See also

ConfigurationProject Configuration