[Guide] Running Docker on your Raspberry Pi

Installing HypriotOS

In order to run Docker on your Raspberry Pi, HypriotOS is an easy way to get started. The hypriot crew has made a flash tool that guides you through the setup and lets you configure parts such as hostname and the WiFi network configuration. The beginning of this guide will overlap with the guide found at hypriot’s Github page and move to getting started with Docker. Furthermore it abstracts away the underlying commands to unmount your SD card and to copy the image to the SD card normally using dd.The first step is to download the ‘flash’ bash script and make it executable.

wget$(uname -s)/flash  
chmod +x flash  
sudo mv flash /usr/local/bin/flash  

Depending on your operating system follow one of the steps below.
On OSX the dependencies can be installed using Homebrew as seen below:

brew install pv  
brew install awscli  

On Linux the dependencies are installed with apt-get (and pip):

sudo apt-get install -y pv curl python-pip  
sudo pip install awscli  

Flashing the SD card

You can either specify a link to a Hypriot image or download it first from This guide is written using Version 0.6.1 Hector.
As mentioned there are different options to change. The following only shows how to change the hostname to node21. After the image is downloaded, run the following command for each of your SD cards (with the desired hostname):

$ flash --hostname node21 hypriot-rpi-20151115-132854.img

And the disk was choosen to be /dev/disk2 in our case – your disk might be a different one!
One of the benefits of using flash instead of dd is that you can see the progression while writing to the SD card.

Accessing the Raspberry Pi

To access your Raspberry Pi you can connect a monitor and a keyboard, and then simply login as ‘root’ with password ‘hypriot’.
An alternative method is to use ssh, and connect through the network. You will need the IP of your Raspberry Pi (can be found on your router) or use Avahi to connect to hostname.local – in this case node22.local.

You can connect through ssh in the following way:

$ ssh [email protected]

or using Avahi

$ ssh [email protected]

You will be asked if you trush a fingerprint, and you do so by typing ‘yes’.

Static IP (optional)

If your want a static IP for your Raspberry Pi you can do so by changing your network configuration in the following way:

$ sudo nano /etc/network/interfaces

This will open the nano editor with your network configuration.
Depending on your router you may need to adapt the file a little. Most of the values should be easy to find if your own computer is connected to the network by running ifconfig or ipconfig.
Delete all of the lines in the file, replace it with the following, and set the IP you want after address:

auto lo  
iface lo inet loopback

allow-hotplug eth0  
iface eth0 inet static  
address **<YOUR IP GOES HERE>**  

iface eth0 inet6 auto

allow-hotplug wlan0  
iface wlan0 inet dhcp  
pre-up /usr/bin/occi  
wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf  
iface default inet dhcp  

Running Docker

Now you are ready to execute Docker commands on your Raspberry Pi.
You can start running docker images to see your available images.
Version 0.6.1 is bundled with two images.

$ docker images
REPOSITORY                  TAG                 IMAGE ID            CREATED             VIRTUAL SIZE  
hypriot/rpi-swarm           latest              039c550f6208        11 weeks ago        10.92 MB  
hypriot/rpi-busybox-httpd   latest              c7278d0bf2e2        7 months ago        2.156 MB  

From the busybox image we can launch a simple webserver in a container.

$ docker run -d -p 80:80 hypriot/rpi-busybox-httpd

The command above creates a new container from the busybox image. The -d arguments tells Docker to start it as a daemon, and -p 80:80 means that port 80 on the machine should bind to the container’s port 80.

Now the container can be found among the running containers.

$ docker ps
CONTAINER ID        IMAGE                       COMMAND                  CREATED             STATUS              PORTS                NAMES  
8e90311ea84a        hypriot/rpi-busybox-httpd   "/bin/busybox httpd -"   2 minutes ago       Up About a minute>80/tcp   cocky_poincare  

Now you can access your web server from your browser by visiting its IP address. Your can either use the direct IP (, Avahi (http://node21.local/) or through localhost (http://localhost). You should see something like the page below.
 Now you have Docker running on your Raspberry Pi. Finding new images on Docker Hub could be the next step. It’s important to note, that Raspberry Pis run on ARM processors, therefore you need ARM images from Docker Hub. You can find a lot of them by searching for “rpi” or “arm”. Once again, the hypriot crew has made an excellent job and created at lot of images on their hypriot docker hub profile.

Martin Jensen


Martin Jensen

Leave a Reply

Your email address will not be published. Required fields are marked *