Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
321 lines (207 sloc) 10.2 KB

Docker Swarm on PI Zero


Please Star the docker-arm repository to show your support. For questions send me a comment on the blog and for bugs/problems raise an issue on the repository.


With the release of the 5 dollar Raspberry Pi Zero computer, there has never been a better time to start building a Docker Swarm. Whether you want to try distributed computing or just build something cool with your Pi Zeros.

In this quick-start guide we will configure Arch Linux ARM or Raspbian, install Docker and then use a laptop or another PC to create a swarm which all our Pi Zeros can join. There are several ways of doing this (called swarm discovery), but we'll keep things simple with a hard-coded list of swarm agents. You can take it further later on through the Swarm Discovery documentation. I've provided some sample images for Node.js, Redis, Ruby and Python so once you're up and running it's over to you to create something awesome.

  • Install & configure Arch Linux ARM
  • Install Docker
  • Configure a Swarm
  • Start the Swarm

You will need:

  • Raspberry PI Zero, at least two
  • At least one Ethernet adapter
  • A computer or Raspberry PI running Linux

This is an example of a fully working cluster, more details available in my IoT cluster blog post

A fully working cluster

Step 1


I would recommend starting with a fresh SD card and Arch Linux, but Rasbpian is also supported with a work-around to enable the latest version of Docker. The version in Jessie's apt repository is going to be out of date.

Prepare the kernel modules and OS

Download the latest Hypriot build of Docker, compatible with Jessie:

$ wget

Now prepare the kernel modules and install extra packages.

sudo apt-get update && sudo apt-get install libapparmor1
echo overlay | sudo tee -a /etc/modules
sudo modprobe overlay
sudo dpkg -i docker-hypriot_1.11.1_armhf.deb

Arch Linux

Arch Linux ARM (aka ALARM) is a minimal Raspberry PI Linux distribution which gives us a great platform to run Docker. It also runs a rolling-release meaning the packages available in its pacman software manager are always bleeding-edge.

There is no .img or .iso file available for ALARM, instead we will need another Raspbery PI or Linux computer and an SD card reader where we can partition the card, format it and then un-tar a root filesystem provided by Arch Linux ARM.

Head over to and click the Installation tab and follow the instructions.

Step 2

Booting and configuring network

From this point continue with the steps that will work with either Raspbian or Arch Linux ARM

Arch Linux ARM does not come with any wi-fi packages pre-installed, but if you have an Ethernet adapter this will automatically connect to your network and obtain an IP address via DHCP. To find the IP address of your PI you can either go to the administration page of your ISP's router or run the nmap network scanner.

Example network scan:

$ nmap -sP


$ ssh alarm@

Attempt to use SSH to connect to each IP address until you find the PI

The PI's default username and password are: alarm/alarm and root/root. By default sudo is an optional package, which you can install through pacman. Pacman is the equivalent to apt-get on Raspbian.

Make a note of the IP address of the PI Zero and make sure you change the default passwords immediately.

Configure Static IP address (optional)

This assumes a USB ethernet adapter named eth0. If you would like to set up an IP address that is predictable and which won't change, then edit the following file remembering to change the IP address to something that suits your needs.

File: /etc/systemd/network/



This optional step needs a reboot and has only been tested on Arch Linux.

Step 4

Configure Arch

Install some packages that we will need later on in the tutorial.

pacman -Syu sudo cronie git wget

Switch to root with su and edit the /etc/sudoers file in nano or vim.

Uncomment the below starting # %wheel

## Same thing without a password

Save the file and now you will be able to use the sudo command as the alarm user.

At this point you could also switch over to a wi-fi adapter by installing the wpa_actiond package from pacman. This installs the wifi-menu program allowing you to configure the SSID and password.

Pro-tip: you can plug the SD card into a Model B/B+ Raspberry PI to take advantage of its on-board ethernet adapter.

Step 3

Installing Docker

Installing Docker could not be easier thanks to the hard work of the Arch Linux community. Go ahead and type in the following:

pacman -Sy docker

Once installed, let's configure Docker.

systemctl enable docker
systemctl start docker
sudo usermod alarm -aG docker

Please reboot the system. Congratulations, you now have Docker fully working on your PI Zero!

Step 4

Enable the Swarm

Most Docker images are only available for regular PCs (i.e. x64) so for the Raspberry PI we need to use specific versions for the ARM architecture. Pull down the Docker swarm image:

docker pull alexellis2/swarm-arm:v6

Now we will edit the Docker daemon's configuration to allow any computer on our network to control it. Please beware that this setting should only be used within your internal network, if you wanted to use it over the Internet then look into TLS encryption in Docker documentation.

Edit /usr/lib/systemd/system/docker.service and on the line ExecStart add the following:

-H tcp://

Your line will now look a bit like this:

ExecStart=/usr/bin/docker daemon -H fd:// -H tcp:// 

Now reboot the system or reload the configuration with:

sudo systemctl daemon-reload
sudo systemctl restart docker

Step 6

Start the Swarm manager

Now log into either one of your PI Zeros or your PC/laptop.

Take a note of the IP addresses of all the PI Zeros and edit the --nodes:// parameter below:



On a PC:

docker run -d --name manage -p 2376:2375 swarm manage nodes://,

On a PI Zero:

$ docker run -d --name manage -p 2376:2375 alexellis2/swarm-arm:v6 manage nodes://,

To check on the status of the swarm manager:

$ docker logs manage
time="2016-04-14T08:20:24Z" level=info msg="Listening for HTTP" addr=":2375" proto=tcp
time="2016-04-14T08:20:26Z" level=info msg="Registered Engine zero1 at"
time="2016-04-14T08:20:27Z" level=info msg="Registered Engine zero2 at"

Step 7

Querying the Swarm

You now have a fully working swarm, to query the swarm as a whole connect to the manager container we just started.

export DOCKER_HOST=tcp://localhost:2376

Let's find out how many resources we have available:

$ docker info
Containers: 6
 Running: 0
 Paused: 0
 Stopped: 0
Images: 23
Role: primary
Strategy: spread
Filters: health, port, dependency, affinity, constraint
Nodes: 2
  └ Containers: 1
  └ Reserved CPUs: 0 / 1
  └ Reserved Memory: 0 B / 504 MiB
  └ Labels: executiondriver=native-0.2, kernelversion=4.1.21-1-ARCH, operatingsystem=Arch Linux ARM, storagedriver=aufs
  └ Containers: 5
  └ Reserved CPUs: 0 / 1
  └ Reserved Memory: 0 B / 504 MiB
  └ Labels: executiondriver=native-0.2, kernelversion=4.1.21-1-ARCH, operatingsystem=Arch Linux ARM, storagedriver=aufs
CPUs: 2
Total Memory: 1008 MiB

So that is 2x CPUs and 1GB of RAM.

Step 8

Running a container in the swarm

$ export DOCKER_HOST=tcp://localhost:2376

$ docker pull alexellis2/ruby-arm:v6
$ mkdir -p ruby_hello_world
$ cd ruby_hello_world

Add the following main.rb file:

who = "Ruby"
puts "Hello #{who}!"

Enter the following Dockerfile

FROM alexellis2/ruby-arm:v6
ADD ./main.rb ./
CMD ["ruby", "main.rb"]

Let's start the Ruby application, the swarm manager will find a suitable agent and start executing it.

$ docker build -t ruby_hello_world:v6 .
$ docker run --name ruby_hello_1 ruby_hello_world:v6
Hello Ruby!

Now if you want to find out more information about the container that was started use docker inspect and the name of the container which we specified:

$ docker inspect ruby_hello_1

Spreading images between the Swarm

The easiest way to spread your images between the Swarm is to push them to the Docker Hub with docker push then log into each PI and use docker pull to bring it into the local library. If you build an image pointing at the swarm manager then the manager will pick a random Pi Zero to do the build.

The alternative method is to log into each Pi and build the image from source as we did above.

Wrapping up

This is the end of the quick-start tutorial. You now have a fully working PI Zero Swarm and are ready to start exploring images built specifically for ARM. Please see the repository docker-arm over at Github for compatible ARMv6 images:

alexellis's ARMv6 Images

Questions? Send me a message on the blog or through Twitter at @alexellisuk.

See also:

Additional instructions are available for the Raspberry Pi 2/3, including how to set up a Swarm using Consul for discovery instead of using the hard-coded nodes:// method.

Docker for Raspberry PI tutorial

Docker Swarm documentation

Copyright Alex Ellis 2016

You can’t perform that action at this time.