Documentation
Documentation
swarmctl is a small Go daemon that runs inside a Docker Swarm cluster, on a manager node, with the Docker socket mounted. It does two largely independent jobs:
- A deploy endpoint.
POST /v1/update/{serviceName}?image=…pulls a new image into a running Swarm service. CI calls it instead of holding a SSH key. - A background reconciler. It watches the Docker event stream and keeps
Cloudflare Tunnel ingress, DNS records, and Access applications in sync with
the services that carry
cloudflared.tunnel.*labels.
Service discovery is entirely label-driven — swarmctl itself has no per-service configuration.
Start here
Deploy swarmctl to the swarm, give it credentials, make the first call.
The label contract: enabled, port, hostname, access policy.
Every environment variable, and how Docker secrets are read.
Endpoints, auth, rate limiting, response shapes.
Going deeper
Event watchers, the sync path, and removal reconciliation.
Prometheus metrics, the Grafana dashboard, Discord logging, Pushover alerts.
Startup exits, missing zones, duplicate DNS records, hostnames that never disappear.
Dev loop, package layout, and the invariants to preserve.
The one thing to know first
swarmctl talks to the Docker API as a manager, and the deploy endpoint will
change the image of any service you name. The bearer token in
AUTH_TOKEN is
therefore root-equivalent on the cluster. Only /v1/* is authenticated —
/ping, /version, and /metrics are deliberately public, so put the service
behind the tunnel and treat the token as a cluster credential.