Deployment Workflow¶

finchctl service deploy sets up the entire Finch stack on a remote Linux server over SSH. This page explains what it does, what it requires, and how to update or remove a running stack.

Prerequisites¶

Deploy¶

finchctl service deploy root@finch.example.com

If your SSH user differs from root, use user@host. A non-standard SSH port can be appended: user@host:2222.

If the service hostname differs from the SSH target (for example, you deploy via IP but the service is reached via a DNS name), pass the hostname explicitly:

finchctl service deploy --service.host finch.example.com 10.19.80.100

What deploy does¶

1. Check prerequisites

Verifies that sudo, curl, and passwordless sudo are available on the remote host. Fails with a clear message if any requirement is missing.

2. Install Docker

Checks whether Docker is already installed and running. If not, downloads and runs the official installer from get.docker.com. Also copies a Docker daemon configuration file - enabling IPv6 - and restarts the Docker service.

3. Create directory hierarchy

Creates the working directory /var/lib/finch/ with subdirectories for each service: grafana/, loki/, mimir/, pyroscope/, alloy/, traefik/. Each directory is owned by the appropriate service user.

4. Copy service configurations

Copies embedded configuration files for Loki, Mimir, Pyroscope, Alloy, Traefik, and Grafana (dashboards and alerting rules) to their respective directories.

5. Generate mTLS certificates

Generates a per-deployment CA and client certificate (ECDSA P-256, 90-day validity). The CA certificate is uploaded to the server. The client certificate and private key are stored locally in ~/.config/finch.json and are used by every subsequent finchctl command to authenticate with the Finch service.

6. Generate signing secret

Creates the server configuration with a freshly generated 32-byte random signing secret. This secret is used to sign and validate all agent JWT.

7. Start containers

Runs docker compose up --detach. The compose file embeds configuration hashes so that containers are automatically restarted when their configuration changes on the next service update.

8. Health check

Polls the health status of six containers - traefik, finch, grafana, loki, mimir, pyroscope every 2 seconds for up to 180 seconds. If any container reports unhealthy five times in a row, or if the timeout is reached, deployment fails and the last container logs are shown.

Update¶

finchctl service update root@finch.example.com

Updates an already-running stack: pulls fresh configuration from the embedded assets, pulls new container images if available, and restarts any containers whose configuration or image has changed.

What service update does:

1. Reads server configuration to determine the hostname and TLS mode, no flags needed to identify the target stack.
2. Re-copies all service configuration files (Loki, Traefik routing, Alloy, Mimir, Pyroscope, Grafana dashboards and alerts).
3. Runs docker compose pull --policy missing to fetch new image versions.
4. Runs docker compose up --detach, only containers with changed configuration or a new image are restarted.
5. Runs the same 180-second health check as deploy.
6. Prunes unused images with docker image prune --force.

To apply a new custom TLS certificate during an update:

finchctl service update \
  --service.customtls \
  --service.customtls.cert /path/to/new/cert.pem \
  --service.customtls.key  /path/to/new/key.pem \
  root@finch.example.com

Teardown¶

finchctl service teardown root@finch.example.com

Completely removes the stack from the remote server:

1. Runs docker compose down, which stops all containers.
2. Removes /var/lib/finch/ and all configuration files.
3. Removes the stack entry from ~/.config/finch.json on the local machine.

Dry run¶

Any of the three commands accept --run.dry-run to print the SSH commands that would be executed without actually running them:

finchctl service deploy --run.dry-run root@finch.example.com

The readiness health check is skipped in dry-run mode.