Configuration Reference¶

Compose Farm uses a YAML configuration file to define hosts and stack assignments.

Config File Location¶

Compose Farm looks for configuration in this order:

-c / --config flag (if provided)
CF_CONFIG environment variable
./compose-farm.yaml (current directory)
$XDG_CONFIG_HOME/compose-farm/compose-farm.yaml (defaults to ~/.config)

Use -c / --config to specify a custom path:

cf ps -c /path/to/config.yaml

Or set the environment variable:

export CF_CONFIG=/path/to/config.yaml

Examples¶

Single host (local-only)¶

# Required: directory containing compose files
compose_dir: /opt/stacks

# Define local host
hosts:
  local: localhost

# Map stacks to the local host
stacks:
  plex: local
  sonarr: local
  radarr: local

Multi-host (full example)¶

# Required: directory containing compose files (same path on all hosts)
compose_dir: /opt/compose

# Optional: auto-regenerate Traefik config
traefik_file: /opt/traefik/dynamic.d/compose-farm.yml
traefik_stack: traefik

# Define Docker hosts
hosts:
  nuc:
    address: 192.168.1.10
    user: docker
  hp:
    address: 192.168.1.11
    user: admin

# Map stacks to hosts
stacks:
  # Single-host stacks
  plex: nuc
  sonarr: nuc
  radarr: hp

  # Multi-host stacks
  dozzle: all                    # Run on ALL hosts
  node-exporter: [nuc, hp]       # Run on specific hosts

Settings Reference¶

compose_dir (required)¶

Directory containing your compose stack folders. Must be the same path on all hosts.

compose_dir: /opt/compose

Directory structure:

/opt/compose/
├── plex/
│   ├── docker-compose.yml    # or compose.yaml
│   └── .env                  # optional environment file
├── sonarr/
│   └── docker-compose.yml
└── ...

Supported compose file names (checked in order): - compose.yaml - compose.yml - docker-compose.yml - docker-compose.yaml

traefik_file¶

Path to auto-generated Traefik file-provider config. When set, Compose Farm regenerates this file after up, down, restart, and update commands.

traefik_file: /opt/traefik/dynamic.d/compose-farm.yml

traefik_stack¶

Stack name running Traefik. Stacks on the same host are skipped in file-provider config (Traefik's docker provider handles them).

traefik_stack: traefik

Hosts Configuration¶

Basic Host¶

hosts:
  myserver:
    address: 192.168.1.10

With SSH User¶

hosts:
  myserver:
    address: 192.168.1.10
    user: docker

If user is omitted, the current user is used.

With Custom SSH Port¶

hosts:
  myserver:
    address: 192.168.1.10
    user: docker
    port: 2222  # SSH port (default: 22)

Localhost¶

For stacks running on the same machine where you invoke Compose Farm:

hosts:
  local: localhost

No SSH is used for localhost stacks.

Multiple Hosts¶

hosts:
  nuc:
    address: 192.168.1.10
    user: docker
  hp:
    address: 192.168.1.11
    user: admin
  truenas:
    address: 192.168.1.100
  local: localhost

Stacks Configuration¶

Single-Host Stack¶

stacks:
  plex: nuc
  sonarr: nuc
  radarr: hp

Multi-Host Stack¶

For stacks that need to run on every host (e.g., log shippers, monitoring agents):

stacks:
  # Run on ALL configured hosts
  dozzle: all
  promtail: all

  # Run on specific hosts
  node-exporter: [nuc, hp, truenas]

Common multi-host stacks: - Dozzle - Docker log viewer (needs local socket) - Promtail/Alloy - Log shipping (needs local socket) - node-exporter - Host metrics (needs /proc, /sys) - AutoKuma - Uptime Kuma monitors (needs local socket)

Stack Names¶

Stack names must match directory names in compose_dir:

compose_dir: /opt/compose
stacks:
  plex: nuc      # expects /opt/compose/plex/docker-compose.yml
  my-app: hp     # expects /opt/compose/my-app/docker-compose.yml

State File¶

Compose Farm tracks deployment state in compose-farm-state.yaml, stored alongside the config file.

For example, if your config is at ~/.config/compose-farm/compose-farm.yaml, the state file will be at ~/.config/compose-farm/compose-farm-state.yaml.

deployed:
  plex: nuc
  sonarr: nuc

This file records which stacks are deployed and on which host.

Don't edit manually. Use cf refresh to sync state with reality.

Environment Variables¶

In Compose Files¶

Your compose files can use .env files as usual:

/opt/compose/plex/
├── docker-compose.yml
└── .env

Compose Farm runs docker compose which handles .env automatically.

In Traefik Labels¶

When generating Traefik config, Compose Farm resolves ${VAR} and ${VAR:-default} from:

The stack's .env file
Current environment

Config Commands¶

Initialize Config¶

cf config init

Creates a new config file with documented examples.

Validate Config¶

cf config validate

Checks syntax and schema.

Show Config¶

cf config show

Displays current config with syntax highlighting.

Edit Config¶

cf config edit

Opens config in $EDITOR.

Show Config Path¶

cf config path

Prints the config file location (useful for scripting).

Create Symlink¶

cf config symlink                          # Link to ./compose-farm.yaml
cf config symlink /path/to/my-config.yaml  # Link to specific file

Creates a symlink from the default location (~/.config/compose-farm/compose-farm.yaml) to your config file. Use --force to overwrite an existing symlink.

Validation¶

Local Validation¶

Fast validation without SSH:

cf check --local

Checks: - Config syntax - Stack-to-host mappings - Compose file existence

Full Validation¶

cf check

Additional SSH-based checks: - Host connectivity - Mount point existence - Docker network existence - Traefik label validation

Stack-Specific Check¶

cf check jellyfin

Shows which hosts can run the stack (have required mounts/networks).

Example Configurations¶

Minimal¶

compose_dir: /opt/compose

hosts:
  server: 192.168.1.10

stacks:
  myapp: server

Home Lab¶

compose_dir: /opt/compose

hosts:
  nuc:
    address: 192.168.1.10
    user: docker
  nas:
    address: 192.168.1.100
    user: admin

stacks:
  # Media
  plex: nuc
  sonarr: nuc
  radarr: nuc

  # Infrastructure
  traefik: nuc
  portainer: nuc

  # Monitoring (on all hosts)
  dozzle: all

Production¶

compose_dir: /opt/compose
network: production
traefik_file: /opt/traefik/dynamic.d/cf.yml
traefik_stack: traefik

hosts:
  web-1:
    address: 10.0.1.10
    user: deploy
  web-2:
    address: 10.0.1.11
    user: deploy
  db:
    address: 10.0.1.20
    user: deploy

stacks:
  # Load balanced
  api: [web-1, web-2]

  # Single instance
  postgres: db
  redis: db

  # Infrastructure
  traefik: web-1

  # Monitoring
  promtail: all