diff --git a/README.md b/README.md index b20e12e..aced923 100644 --- a/README.md +++ b/README.md @@ -43,8 +43,8 @@ A minimal CLI tool to run Docker Compose commands across multiple hosts via SSH. - [What Compose Farm doesn't do](#what-compose-farm-doesnt-do) - [Installation](#installation) - [SSH Authentication](#ssh-authentication) - - [SSH Agent (default)](#ssh-agent-default) - - [Dedicated SSH Key (recommended for Docker/Web UI)](#dedicated-ssh-key-recommended-for-dockerweb-ui) + - [SSH Agent](#ssh-agent) + - [Dedicated SSH Key (default for Docker)](#dedicated-ssh-key-default-for-docker) - [Configuration](#configuration) - [Single-host example](#single-host-example) - [Multi-host example](#multi-host-example) @@ -208,9 +208,9 @@ cp .envrc.example .envrc && direnv allow Compose Farm uses SSH to run commands on remote hosts. There are two authentication methods: -### SSH Agent (default) +### SSH Agent -Works out of the box if you have an SSH agent running with your keys loaded: +Works out of the box when running locally if you have an SSH agent running with your keys loaded: ```bash # Verify your agent has keys @@ -220,9 +220,9 @@ ssh-add -l cf up --all ``` -### Dedicated SSH Key (recommended for Docker/Web UI) +### Dedicated SSH Key (default for Docker) -When running compose-farm in Docker, the SSH agent connection can be lost (e.g., after container restart). The `cf ssh` command sets up a dedicated key that persists: +When running in Docker, SSH agent sockets are ephemeral and can be lost after container restarts. The `cf ssh` command sets up a dedicated key that persists: ```bash # Generate key and copy to all configured hosts @@ -250,6 +250,13 @@ volumes: - cf-ssh:${CF_HOME:-/root}/.ssh ``` +**Option 3: SSH agent forwarding** - if you prefer using your host's ssh-agent +```yaml +volumes: + - ${SSH_AUTH_SOCK}:/ssh-agent:ro +``` +Note: Requires `SSH_AUTH_SOCK` environment variable to be set. The socket path is ephemeral and changes across sessions. + Run setup once after starting the container (while the SSH agent still works): ```bash diff --git a/docker-compose.yml b/docker-compose.yml index 7daa220..8eaaf59 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -6,7 +6,6 @@ services: # Defaults to root (0:0) for backwards compatibility user: "${CF_UID:-0}:${CF_GID:-0}" volumes: - - ${SSH_AUTH_SOCK}:/ssh-agent:ro # Compose directory (contains compose files AND compose-farm.yaml config) - ${CF_COMPOSE_DIR:-/opt/stacks}:${CF_COMPOSE_DIR:-/opt/stacks} # SSH keys for passwordless auth (generated by `cf ssh setup`) @@ -15,6 +14,8 @@ services: - ${CF_SSH_DIR:-~/.ssh/compose-farm}:${CF_HOME:-/root}/.ssh/compose-farm # Option 2: Named volume - managed by Docker, shared between services # - cf-ssh:${CF_HOME:-/root}/.ssh + # Option 3: SSH agent forwarding (uncomment if using ssh-agent) + # - ${SSH_AUTH_SOCK}:/ssh-agent:ro environment: - SSH_AUTH_SOCK=/ssh-agent # Config file path (state stored alongside it) @@ -31,13 +32,14 @@ services: # Run as current user to preserve file ownership on mounted volumes user: "${CF_UID:-0}:${CF_GID:-0}" volumes: - - ${SSH_AUTH_SOCK}:/ssh-agent:ro - ${CF_COMPOSE_DIR:-/opt/stacks}:${CF_COMPOSE_DIR:-/opt/stacks} # SSH keys - use the SAME option as cf service above # Option 1: Host path (default) - ${CF_SSH_DIR:-~/.ssh/compose-farm}:${CF_HOME:-/root}/.ssh/compose-farm # Option 2: Named volume # - cf-ssh:${CF_HOME:-/root}/.ssh + # Option 3: SSH agent forwarding (uncomment if using ssh-agent) + # - ${SSH_AUTH_SOCK}:/ssh-agent:ro # XDG config dir for backups and image digest logs (persists across restarts) - ${CF_XDG_CONFIG:-~/.config/compose-farm}:${CF_HOME:-/root}/.config/compose-farm environment: