¶ HiveMind GitOps
¶ Summary
This page explains how HiveMind keeps running services synced with Git. In simple terms: when stack files change in the repo, HiveMind notices and updates Docker Swarm so live services match the approved config.
Technical behavior and flow details are documented below.
HiveMind is the custom GitOps controller used to reconcile Docker Swarm against a Git repository. It fills the role that Flux-style tooling would in a Kubernetes environment, but for Swarm.
¶ What It Does
HiveMind:
- Clones the configured Git repository.
- Watches for changes on the configured branch.
- Reads the stack definitions from Git.
- Compares Git state to the currently deployed Swarm state.
- Deploys new or updated stacks and removes retired stacks.
¶ Current Lab Configuration
The Swarm deployment is configured to watch:
| Setting | Value |
|---|---|
| Git URL | https://github.com/Nichols-HomeLab/Docker-Swarm.git |
| Branch | main |
| Repo path | . |
| Stack file | stacks.yml |
| Poll interval | 60 seconds |
| Notification path | ntfy via SMTP-compatible endpoint |
The controller itself is deployed from Compose-Files/Runners/hivemind.yml as the controller service.
¶ How It Fits This Lab
In this homelab, HiveMind sits between the Docker-Swarm repo and the live Swarm cluster.
Typical flow:
- Stack or compose changes are committed through Git.
- Git review or PR discussion happens first.
- HiveMind polls the repo.
- HiveMind detects the change and reconciles Swarm.
- The running state converges on the Git state.
¶ Stack File Model
Docker-Swarm/stacks.yml is the deployment index. It groups Compose files by stack area, marks each stack enabled or disabled, and lets HiveMind know which compose files should be applied together.
Active stack groups include:
arrbackupdatabasesDNSdownloadersexternalgame-serversmediamonitoringnotificationsrandomregistryreverse-proxyrunnerssecurity
Deprecated Compose files are retained in the repo for history, but they are not part of active stacks.yml deployment.
¶ Reconciliation boundaries
HiveMind owns stack deployment state, not the entire host. It reads Git and calls Docker Swarm APIs for stack lifecycle operations. It does not replace Ansible for host packages, kernel settings, Proxmox configuration, Ceph mounts, node labels, or external Docker volume creation.
That split matters during troubleshooting: if a compose file is correct but a host mount, GPU label, Docker network, or kernel setting is missing, fix the host side from HomeLab automation rather than changing HiveMind.
HiveMind also does not manage Keepalived. The Swarm manager VIP is configured by Ansible before HiveMind starts reconciling stacks.
¶ Troubleshooting
| Symptom | Check |
|---|---|
| Git changed but stack did not update | Confirm HiveMind can pull main, then check controller logs. |
| One service did not start | Check docker stack services <stack> and docker service logs <stack>_<service>. |
| New compose file ignored | Confirm the file is referenced in stacks.yml and the stack is enabled. |
| Old service still exists | Confirm retired-stack handling or remove the stack manually if it predates HiveMind tracking. |
| Notifications missing | Check the ntfy SMTP path configured for HiveMind. |
¶ Safe deployment checks
- Make sure every new compose file is referenced in
stacks.yml. - Keep stack names stable because Swarm service names are derived from them.
- Keep secrets out of committed compose files unless they are intentionally non-secret placeholders.
- Prefer labels for Traefik, Homepage, and AutoKuma so routing and monitoring stay close to the service definition.
¶ Why Use It
- Keeps Docker Swarm changes Git-first.
- Makes the desired state easier to audit.
- Reduces ad-hoc manual drift.
- Pairs well with Ansible, which focuses more on VM and host lifecycle.
¶ Related Repositories
- HiveMind: controller source and image build repo.
- Docker-Swarm: compose files, stacks, and stack-related operational assets.
- HomeLab: Ansible, Proxmox, and host automation.
