March 16, 2026
The Ultimate Edge Cluster: Setting up a 3-Node Swarm on Raspberry Pi 5 (2026)
Learn how to harness the power of the Raspberry Pi 5 to build a low-latency, high-availability edge cluster. We walk through the hardware setup, Swarm initialization, SwarmCLI integration, and production optimizations for AI and IoT workloads.
By 2026, the Raspberry Pi 5 has become the go-to hardware for prosumer edge computing. Its quad-core ARM Cortex-A76 CPU, 8GB RAM option, PCIe NVMe support, and improved thermals make it powerful enough for real production workloads - especially when clustered.
A single Pi is still a single point of failure. This guide walks you through building a compact, high-availability 3-node Docker Swarm cluster that delivers fault tolerance, easy scaling, and built-in load balancing while consuming under 40W total. No Kubernetes complexity - just native Swarm orchestration paired with SwarmCLI, the k9s-inspired TUI that makes managing the cluster effortless.
Docker Swarm shines at the edge: lightweight control plane, simple overlay networking, rolling updates, and seamless service replication. On Pi 5 hardware, the overhead is minimal, leaving maximum resources for your AI models, IoT services, or media workloads.
Why Docker Swarm for Edge Clusters in 2026?
Kubernetes on Raspberry Pi often struggles with control-plane bloat and complex networking. Docker Swarm is integrated directly into the Docker Engine, offering:
- Near-zero overhead on resource-constrained ARM devices.
- Built-in features: Service discovery, load balancing, rolling updates, and secrets management.
- Simplicity:
docker stack deployturns a YAML file into a distributed application. - Observability: SwarmCLI gives you real-time visibility without heavy monitoring stacks.
This 3-node "Pikube" (Swarm edition) provides true high availability: if one node fails, Swarm automatically reschedules tasks to healthy nodes.
Phase 1: Hardware Preparation for Swarm
Recommended Bill of Materials:
- 3× Raspberry Pi 5 (8GB models) - essential for running replicated services and AI inference sidecars.
- 3× NVMe SSDs (512GB+) with compatible M.2 HAT+ boards (official Raspberry Pi or Waveshare/GeeekPi).
- PoE+ HATs + a managed Gigabit PoE switch for clean, single-cable power and networking.
- Active cooling cases to prevent thermal throttling under sustained Swarm task load.
OS Setup (on all nodes):
- Install Raspberry Pi OS 64-bit (Bookworm+) or Ubuntu Server 26.04 LTS.
- Enable NVMe boot (update EEPROM and config.txt for PCIe Gen 3).
- Configure static IPs and hostnames:
pi-manager-01,pi-worker-02,pi-worker-03. - Update and reboot:
Terminal
sudo apt update && sudo apt full-upgrade -y && sudo reboot
Phase 2: Docker + Swarm Initialization
Install Docker on all three nodes:
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
sudo reboot
Initialize the Swarm (Manager Node)
On pi-manager-01:
docker swarm init --advertise-addr <MANAGER_IP>
This creates the Raft consensus group and generates worker and manager join tokens.
Join Worker Nodes
On each worker:
docker swarm join --token <WORKER_JOIN_TOKEN> <MANAGER_IP>:2377
For better availability, promote a second manager:
docker node promote pi-worker-02
Verify with SwarmCLI (highly recommended):
Install SwarmCLI on your laptop (brew install eldaratech/tap/swarmcli or download binary), then run:
swarmcli
Navigate with :node. You’ll see real-time node status, CPU/memory usage, and temperature across the entire Swarm - perfect for spotting Pi 5 thermal issues early.
Phase 3: Swarm Networking & Node Labeling
Create an encrypted overlay network for secure service communication:
docker network create --driver overlay --opt encrypted edge-net
Label nodes for placement constraints (critical for edge hardware with attached peripherals):
docker node update --label-add edge-role=manager pi-manager-01
docker node update --label-add edge-role=camera pi-manager-01
docker node update --label-add storage=fast pi-worker-02
These labels allow services to target specific hardware (e.g., camera-only tasks).
Phase 4: Deploying Production Services with Stacks
Swarm’s real power comes from stack deployments. Here’s a complete example for a local AI inference workload (Ollama + OpenWebUI).
Create ai-stack.yml:
version: '3.9'
services:
ollama:
image: ollama/ollama:latest
deploy:
mode: global
resources:
reservations:
cpus: '2.0'
memory: 4G
limits:
cpus: '3.5'
memory: 6G
placement:
constraints:
- node.labels.edge-role == manager
volumes:
- ollama_data:/root/.ollama
networks:
- edge-net
ports:
- '11434:11434'
webui:
image: ghcr.io/open-webui/open-webui:ollama
deploy:
replicas: 2
update_config:
parallelism: 1
delay: 30s
restart_policy:
condition: on-failure
networks:
- edge-net
ports:
- '8080:8080'
depends_on:
- ollama
volumes:
ollama_data:
driver: local
networks:
edge-net:
external: true
Deploy the stack:
docker stack deploy -c ai-stack.yml ai-edge
Swarm handles replication, load balancing, and automatic failover.
Monitor in SwarmCLI:
:service→ see real-time task status.:logs ollama→ stream logs from any replica.:scale ai-edge_webui 3→ dynamically adjust replicas.
Phase 5: Edge-Specific Swarm Optimizations
Resource Constraints & Limits
Always define reservations and limits in production stacks to prevent one service from starving Pi nodes.
Log Management for Long-Running Clusters
On all nodes, configure Swarm-friendly logging in /etc/docker/daemon.json:
{
"log-driver": "json-file",
"log-opts": {
"max-size": "10m",
"max-file": "3"
}
}
Restart: sudo systemctl restart docker.
Secrets & Configs Management
Swarm has native secrets - ideal for edge security:
echo "your-api-key" | docker secret create openai_key -
Reference in stacks:
secrets:
openai_key:
external: true
Business Edition SwarmCLI users get enhanced secret reveal and RBAC controls.
Rolling Updates & Auto-healing
deploy:
update_config:
parallelism: 1
failure_action: rollback
Swarm automatically handles node failures by rescheduling tasks.
Phase 6: Advanced SwarmCLI Usage on Pi Clusters
SwarmCLI turns your edge cluster into a joy to operate:
- Real-time node health with temperature alerts (critical for Raspberry Pi).
- Quick filtering and actions on services/tasks.
- Built-in system metrics panel - no need for full Prometheus on limited hardware.
- Keyboard shortcuts for logs, exec (in BE), and scaling.
Pro tip: Run SwarmCLI in a tmux session on the manager for always-on monitoring.
Phase 7: Troubleshooting Common Swarm Issues on Edge Hardware
Tasks Stuck in Pending:
- Insufficient resources - check with SwarmCLI node view.
- Label/constraint mismatch.
- Disk pressure on NVMe - monitor via SwarmCLI.
Networking Problems:
- Ensure ports 2377 (Swarm), 7946 (discovery), 4789 (overlay) are open.
- Verify overlay network attachment.
Node Rejoin After Failure:
- Drain the node first:
docker node update --availability drain <node> - Re-promote if needed.
Thermal Throttling:
- SwarmCLI highlights affected nodes instantly. Improve cooling or adjust CPU limits.
Backup Strategy:
- Export stacks regularly:
docker stack services ai-edge - Backup volumes with rsync or lightweight tools like restic.
Conclusion: A Palm-Sized, Production-Ready Swarm Edge Cluster
Your 3-node Raspberry Pi 5 Docker Swarm delivers:
- High Availability through Swarm’s built-in orchestration.
- Low Power & Cost - perfect for always-on edge deployments.
- Operational Simplicity with Swarm stacks and SwarmCLI.
- Scalability - add nodes effortlessly as your needs grow.
This setup is ideal for private AI inference, smart home orchestration, video analytics, or homelab experiments.
Next Steps:
- Install SwarmCLI today and connect to your new cluster.
- Star the project on GitHub: eldaratech/swarmcli.
- Consider Business Edition for advanced RBAC, mTLS proxy, and enterprise features.
Questions or issues? Open a GitHub discussion. Happy Swarming at the edge!