Initializing Docker Swarm

This lesson guides you through the process of initializing Docker Swarm on your Raspberry Pi cluster, transforming individual Pis into a powerful, unified computing resource.

By Kevin McAleer,    3 Minutes

Setting Up Docker Swarm on Raspberry Pi

With your Raspberry Pis prepared and running the cloned OS, the next step is to initialize Docker Swarm. Docker Swarm turns a group of Docker engines into a single, virtual Docker engine, where you can deploy and manage containers across multiple Raspberry Pi nodes seamlessly.

What is Docker Swarm?

Docker Swarm is a container orchestration tool, part of Docker, that allows you to manage multiple Docker hosts as a single entity. It’s designed for ease of use and simplicity, making it an excellent choice for beginners and for use with Raspberry Pi clusters.


  • All Raspberry Pis are set up with the cloned Raspberry Pi OS and are networked together.
  • Docker is installed on all Raspberry Pis. Refer to the previous lesson if you haven’t installed Docker yet.

Step 1: Choose a Manager Node

  • In a Docker Swarm, at least one node acts as the manager (or multiple for redundancy), which orchestrates the deployment and manages the cluster state.
  • Decide which Raspberry Pi will be the manager node. Ideally, pick a Pi that you can easily access for administrative tasks.

Step 2: Initializing the Swarm

  1. Open a Terminal on your chosen manager Raspberry Pi.
  2. Run the Docker Swarm Init Command: Execute the following command:

    docker swarm init --advertise-addr <MANAGER_IP>

    Replace <MANAGER_IP> with the IP address of your manager Raspberry Pi. This IP should be static or reserved to prevent issues.

  3. Note the Join Token: Upon successful initialization, Docker will output a token that worker nodes will use to join the Swarm. It looks something like this:

    docker swarm join --token SWMTKN-1-<token_string> <MANAGER_IP>:2377

    Keep this token secure; you’ll need it to add worker nodes to your Swarm.

Step 3: Adding Worker Nodes

  1. Access Each Worker Node: Log into each Raspberry Pi you wish to add as a worker node.
  2. Join the Swarm: On each worker node, execute the join command you noted earlier. This will connect the node to the Swarm as a worker.

Step 4: Verifying the Swarm

  • Check the Swarm’s Status: On the manager node, run:

    docker node ls

    This command lists all nodes in the Swarm, showing their roles (manager or worker) and statuses.

Docker Swarm Management

  • Promoting Nodes: You can promote worker nodes to manager status for redundancy using:

    docker node promote <NODE_NAME>
  • Demoting Nodes: Similarly, managers can be demoted to workers with:

    docker node demote <NODE_NAME>


Initializing Docker Swarm on your Raspberry Pi cluster is a pivotal step in creating a unified computing platform. With Swarm, you can deploy containers across multiple Pis, manage workload distribution, and ensure your applications are highly available. In the upcoming lessons, we’ll explore how to add applications and services to your newly formed Docker Swarm cluster.

< Previous Next >