diff --git a/README.md b/README.md index 638402d..4a195d5 100644 --- a/README.md +++ b/README.md @@ -321,33 +321,35 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Compose Farm - run docker compose commands across multiple hosts -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --version -v Show version and exit │ -│ --install-completion Install completion for the current shell. │ -│ --show-completion Show completion for the current shell, to copy it or │ -│ customize the installation. │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Lifecycle ────────────────────────────────────────────────────────────────────────────╮ -│ up Start services (docker compose up -d). Auto-migrates if host changed. │ -│ down Stop services (docker compose down). │ -│ pull Pull latest images (docker compose pull). │ -│ restart Restart services (down + up). │ -│ update Update services (pull + build + down + up). │ -│ apply Make reality match config (start, migrate, stop as needed). │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Configuration ────────────────────────────────────────────────────────────────────────╮ -│ traefik-file Generate a Traefik file-provider fragment from compose Traefik labels. │ -│ refresh Update local state from running services. │ -│ check Validate configuration, traefik labels, mounts, and networks. │ -│ init-network Create Docker network on hosts with consistent settings. │ -│ config Manage compose-farm configuration files. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Monitoring ───────────────────────────────────────────────────────────────────────────╮ -│ logs Show service logs. │ -│ ps Show status of all services. │ -│ stats Show overview statistics for hosts and services. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --version -v Show version and exit │ +│ --install-completion Install completion for the current shell. │ +│ --show-completion Show completion for the current shell, to │ +│ copy it or customize the installation. │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Lifecycle ──────────────────────────────────────────────────────────────────╮ +│ up Start services (docker compose up -d). Auto-migrates if host │ +│ changed. │ +│ down Stop services (docker compose down). │ +│ pull Pull latest images (docker compose pull). │ +│ restart Restart services (down + up). │ +│ update Update services (pull + build + down + up). │ +│ apply Make reality match config (start, migrate, stop as needed). │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Configuration ──────────────────────────────────────────────────────────────╮ +│ traefik-file Generate a Traefik file-provider fragment from compose │ +│ Traefik labels. │ +│ refresh Update local state from running services. │ +│ check Validate configuration, traefik labels, mounts, and networks. │ +│ init-network Create Docker network on hosts with consistent settings. │ +│ config Manage compose-farm configuration files. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Monitoring ─────────────────────────────────────────────────────────────────╮ +│ logs Show service logs. │ +│ ps Show status of all services. │ +│ stats Show overview statistics for hosts and services. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -376,15 +378,15 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Start services (docker compose up -d). Auto-migrates if host changed. -╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮ -│ services [SERVICES]... Services to operate on │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --all -a Run on all services │ -│ --host -H TEXT Filter to services on this host │ -│ --config -c PATH Path to config file │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Arguments ──────────────────────────────────────────────────────────────────╮ +│ services [SERVICES]... Services to operate on │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --all -a Run on all services │ +│ --host -H TEXT Filter to services on this host │ +│ --config -c PATH Path to config file │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -411,16 +413,17 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Stop services (docker compose down). -╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮ -│ services [SERVICES]... Services to operate on │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --all -a Run on all services │ -│ --orphaned Stop orphaned services (in state but removed from config) │ -│ --host -H TEXT Filter to services on this host │ -│ --config -c PATH Path to config file │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Arguments ──────────────────────────────────────────────────────────────────╮ +│ services [SERVICES]... Services to operate on │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --all -a Run on all services │ +│ --orphaned Stop orphaned services (in state but removed from │ +│ config) │ +│ --host -H TEXT Filter to services on this host │ +│ --config -c PATH Path to config file │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -447,14 +450,14 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Pull latest images (docker compose pull). -╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮ -│ services [SERVICES]... Services to operate on │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --all -a Run on all services │ -│ --config -c PATH Path to config file │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Arguments ──────────────────────────────────────────────────────────────────╮ +│ services [SERVICES]... Services to operate on │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --all -a Run on all services │ +│ --config -c PATH Path to config file │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -481,14 +484,14 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Restart services (down + up). -╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮ -│ services [SERVICES]... Services to operate on │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --all -a Run on all services │ -│ --config -c PATH Path to config file │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Arguments ──────────────────────────────────────────────────────────────────╮ +│ services [SERVICES]... Services to operate on │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --all -a Run on all services │ +│ --config -c PATH Path to config file │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -515,14 +518,14 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Update services (pull + build + down + up). -╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮ -│ services [SERVICES]... Services to operate on │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --all -a Run on all services │ -│ --config -c PATH Path to config file │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Arguments ──────────────────────────────────────────────────────────────────╮ +│ services [SERVICES]... Services to operate on │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --all -a Run on all services │ +│ --config -c PATH Path to config file │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -549,22 +552,23 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Make reality match config (start, migrate, stop as needed). - This is the "reconcile" command that ensures running services match your config file. It - will: - 1. Stop orphaned services (in state but removed from config) 2. Migrate services on - wrong host (host in state ≠ host in config) 3. Start missing services (in config but not - in state) - Use --dry-run to preview changes before applying. Use --no-orphans to only migrate/start - without stopping orphaned services. Use --full to also run 'up' on all services (picks - up compose/env changes). + This is the "reconcile" command that ensures running services match your + config file. It will: + 1. Stop orphaned services (in state but removed from config) 2. Migrate + services on wrong host (host in state ≠ host in config) 3. Start missing + services (in config but not in state) + Use --dry-run to preview changes before applying. Use --no-orphans to only + migrate/start without stopping orphaned services. Use --full to also run 'up' + on all services (picks up compose/env changes). -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --dry-run -n Show what would change without executing │ -│ --no-orphans Only migrate, don't stop orphaned services │ -│ --full -f Also run up on all services to apply config changes │ -│ --config -c PATH Path to config file │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --dry-run -n Show what would change without executing │ +│ --no-orphans Only migrate, don't stop orphaned services │ +│ --full -f Also run up on all services to apply config │ +│ changes │ +│ --config -c PATH Path to config file │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -593,16 +597,16 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Generate a Traefik file-provider fragment from compose Traefik labels. -╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮ -│ services [SERVICES]... Services to operate on │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --all -a Run on all services │ -│ --output -o PATH Write Traefik file-provider YAML to this path (stdout if │ -│ omitted) │ -│ --config -c PATH Path to config file │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Arguments ──────────────────────────────────────────────────────────────────╮ +│ services [SERVICES]... Services to operate on │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --all -a Run on all services │ +│ --output -o PATH Write Traefik file-provider YAML to this path │ +│ (stdout if omitted) │ +│ --config -c PATH Path to config file │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -629,17 +633,17 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Update local state from running services. - Discovers which services are running on which hosts, updates the state file, and - captures image digests. This is a read operation - it updates your local state to match - reality, not the other way around. + Discovers which services are running on which hosts, updates the state file, + and captures image digests. This is a read operation - it updates your local + state to match reality, not the other way around. Use 'cf apply' to make reality match your config (stop orphans, migrate). -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --config -c PATH Path to config file │ -│ --log-path -l PATH Path to Dockerfarm TOML log │ -│ --dry-run -n Show what would change without writing │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --config -c PATH Path to config file │ +│ --log-path -l PATH Path to Dockerfarm TOML log │ +│ --dry-run -n Show what would change without writing │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -667,18 +671,18 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Validate configuration, traefik labels, mounts, and networks. - Without arguments: validates all services against configured hosts. With service - arguments: validates specific services and shows host compatibility. + Without arguments: validates all services against configured hosts. With + service arguments: validates specific services and shows host compatibility. Use --local to skip SSH-based checks for faster validation. -╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮ -│ services [SERVICES]... Services to operate on │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --local Skip SSH-based checks (faster) │ -│ --config -c PATH Path to config file │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Arguments ──────────────────────────────────────────────────────────────────╮ +│ services [SERVICES]... Services to operate on │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --local Skip SSH-based checks (faster) │ +│ --config -c PATH Path to config file │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -706,19 +710,20 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Create Docker network on hosts with consistent settings. - Creates an external Docker network that services can use for cross-host communication. - Uses the same subnet/gateway on all hosts to ensure consistent networking. + Creates an external Docker network that services can use for cross-host + communication. Uses the same subnet/gateway on all hosts to ensure consistent + networking. -╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮ -│ hosts [HOSTS]... Hosts to create network on (default: all) │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --network -n TEXT Network name [default: mynetwork] │ -│ --subnet -s TEXT Network subnet [default: 172.20.0.0/16] │ -│ --gateway -g TEXT Network gateway [default: 172.20.0.1] │ -│ --config -c PATH Path to config file │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Arguments ──────────────────────────────────────────────────────────────────╮ +│ hosts [HOSTS]... Hosts to create network on (default: all) │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --network -n TEXT Network name [default: mynetwork] │ +│ --subnet -s TEXT Network subnet [default: 172.20.0.0/16] │ +│ --gateway -g TEXT Network gateway [default: 172.20.0.1] │ +│ --config -c PATH Path to config file │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -746,17 +751,18 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Manage compose-farm configuration files. -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Commands ─────────────────────────────────────────────────────────────────────────────╮ -│ init Create a new config file with documented example. │ -│ edit Open the config file in your default editor. │ -│ show Display the config file location and contents. │ -│ path Print the config file path (useful for scripting). │ -│ validate Validate the config file syntax and schema. │ -│ symlink Create a symlink from the default config location to a config file. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Commands ───────────────────────────────────────────────────────────────────╮ +│ init Create a new config file with documented example. │ +│ edit Open the config file in your default editor. │ +│ show Display the config file location and contents. │ +│ path Print the config file path (useful for scripting). │ +│ validate Validate the config file syntax and schema. │ +│ symlink Create a symlink from the default config location to a config │ +│ file. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -785,17 +791,18 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Show service logs. -╭─ Arguments ────────────────────────────────────────────────────────────────────────────╮ -│ services [SERVICES]... Services to operate on │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --all -a Run on all services │ -│ --host -H TEXT Filter to services on this host │ -│ --follow -f Follow logs │ -│ --tail -n INTEGER Number of lines (default: 20 for --all, 100 otherwise) │ -│ --config -c PATH Path to config file │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Arguments ──────────────────────────────────────────────────────────────────╮ +│ services [SERVICES]... Services to operate on │ +╰──────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --all -a Run on all services │ +│ --host -H TEXT Filter to services on this host │ +│ --follow -f Follow logs │ +│ --tail -n INTEGER Number of lines (default: 20 for --all, 100 │ +│ otherwise) │ +│ --config -c PATH Path to config file │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -823,10 +830,10 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Show status of all services. -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --config -c PATH Path to config file │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --config -c PATH Path to config file │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ``` @@ -854,14 +861,14 @@ Full `--help` output for each command. See the [Usage](#usage) table above for a Show overview statistics for hosts and services. - Without --live: Shows config/state info (hosts, services, pending migrations). With - --live: Also queries Docker on each host for container counts. + Without --live: Shows config/state info (hosts, services, pending migrations). + With --live: Also queries Docker on each host for container counts. -╭─ Options ──────────────────────────────────────────────────────────────────────────────╮ -│ --live -l Query Docker for live container stats │ -│ --config -c PATH Path to config file │ -│ --help -h Show this message and exit. │ -╰────────────────────────────────────────────────────────────────────────────────────────╯ +╭─ Options ────────────────────────────────────────────────────────────────────╮ +│ --live -l Query Docker for live container stats │ +│ --config -c PATH Path to config file │ +│ --help -h Show this message and exit. │ +╰──────────────────────────────────────────────────────────────────────────────╯ ```