←Back to Blog

March 16, 2026

The Ultimate Edge Cluster: Setting up a 3-Node Swarm on Raspberry Pi 5 (2026)

Build a high-availability 3-node Docker Swarm on Raspberry Pi 5: hardware, swarm init, SwarmCLI, and production tuning for AI and IoT workloads, under 40 W.

The Ultimate Edge Cluster: Setting up a 3-Node Swarm on Raspberry Pi 5 (2026)

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. And if you have read that Swarm is dead, it is not: Docker Swarm is still maintained and supported in 2026. 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 deploy turns 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):

  1. Install Raspberry Pi OS 64-bit (Bookworm+) or Ubuntu Server 26.04 LTS.
  2. Enable NVMe boot (update EEPROM and config.txt for PCIe Gen 3).
  3. Configure static IPs and hostnames: pi-manager-01, pi-worker-02, pi-worker-03.
  4. 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:

Terminal
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:

Terminal
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:

Terminal
docker swarm join --token <WORKER_JOIN_TOKEN> <MANAGER_IP>:2377

For better availability, promote a second manager:

Terminal
docker node promote pi-worker-02

Verify with SwarmCLI (highly recommended):

Install SwarmCLI on your laptop (brew tap eldara-tech/tap && brew install swarmcli or download binary), then run:

Terminal
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:

Terminal
docker network create --driver overlay --opt encrypted edge-net

Label nodes for placement constraints (critical for edge hardware with attached peripherals):

Terminal
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:

Terminal
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:

Terminal
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.
  • l on the ollama service → stream logs from any replica.
  • s on ai-edge_webui → 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:

Terminal
{
  "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:

Terminal
echo "your-api-key" | docker secret create openai_key -

Reference in stacks:

Terminal
secrets:
  openai_key:
    external: true

Business Edition SwarmCLI users get enhanced secret reveal and RBAC controls.

Rolling Updates & Auto-healing

Terminal
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.

Frequently asked questions

Can Raspberry Pi 5 run Docker Swarm? Yes. Docker Engine runs on the 64-bit Raspberry Pi OS and on Ubuntu Server for arm64, and Swarm mode is part of the engine. Three Pi 5 boards with 8 GB, NVMe storage and active cooling make a cluster with one manager and two workers that survives a node failure.

How many Raspberry Pis do I need for a Swarm cluster? Three is the practical minimum for high availability: with three managers the cluster keeps quorum when one node fails. Two nodes give you no fault tolerance at the manager level. Five is the next useful size.

How much power does a 3-node Raspberry Pi 5 Swarm use? Under 40 W for the whole cluster under load with PoE+ HATs, which is why a Pi swarm is the usual choice for an always-on edge or homelab cluster.

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:

  1. Install SwarmCLI today and connect to your new cluster.
  2. Star the project on GitHub: Eldara-Tech/swarmcli.
  3. Consider Business Edition for advanced RBAC, mTLS proxy, and enterprise features.

Questions or issues? Open a GitHub discussion. Happy Swarming at the edge!

2026 Docker Swarm Mastery Series