Docker on Raspberry with GUI

This post describes how to setup you raspberry from scratch for running, monitoring and deploying docker container, monitoring the raspberry system and accessing the gpio pins.

This all will be done without any manual setup on the raspberry so its 100% repeatable.

You will be able to:

#1 Prepare your system

We will use the hypriot “flash” tool for writing the image to the sd card because this works with Linux, OSX and Windows.

So first follow the setup instructions on (we will do this here for OSX).

Open a terminal and type:

brew install pv curl unzip
curl -O$(uname -s)/flash
chmod +x flash
sudo mv flash /usr/local/bin/flash

#2 Setup the raspberry operating system on sd card

Now we flash the image to the sd card.

Before you insert the sd card open a terminal and type:

flash --hostname rpi-docker-host

This command will download the operating system image for your raspberry and guide you to write it to the s card. The provided hostname will be the host name of your raspberry device.

If the program finishes, your sd card is flashed with the raspberry operating system and you can now plug it in and boot your raspberry.

#3 Log in to your raspberry

After the raspberry booted the new sd card image you can log in by typing:

ssh pirate@rpi-docker-host

The default password is hypriot but you should change this (passwd).

You can also use a ssh-key for authentication so you don’t have to type the password again and again:

#4 Fix broken docker-compose

As docker-compose makes things more reproducable but is broken in the actual hypriot image, we will fix this by typing this in to the raspberry terminal:

sudo easy_install --upgrade pip
sudo pip uninstall docker docker-compose -y
sudo pip install docker==2.3.0
sudo pip install docker-compose==1.14.0

*Note: pip is also broken, so we updated it first 😉

#5 Setup portainer for container management

Log into your raspberry and type:

nano docker-compose.yml

This will create a file named docker-compose.yml. Insert the following content:

version: "3"
    image: neoraptor/rpi-monitor
    privileged: true
      - "80:8888"
    restart: unless-stopped
    image: portainer/portainer
      - "81:9000"
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    restart: unless-stopped

Press CTRL + X, confirm write content to file by typing ‘y’ and press return.

Bring up the container by typing:

docker-compose up -d

This will download the needed images and start the container.

"docker ps" will show you the running container and their exposed ports.

#6 Access the raspberry monitor app

Open your browser and goto http://rpi-docker-host.

#7 Access the container management app (portainer)

Open your browser and goto http://rpi-docker-host:81

You will be asked to set a user name and password, do so.

Now you have to choose if you which to manage a docker swarm or a local docker insatnce. Choose local and press connect.

You are now able to spawn and manage docker container via web interface.

Get an overview: Documentation:

#8 Setup webiopi via portainer

Navigate to “Containers” in the site menu. You will see our previous started container responsible for the monitor and portainer app.

Now we would like to add the webiopi app for accessing the gpio-pins via web-interface.

So click on “+ Add container”.

Name the container "rpi_webiopi".

Under “Image configuration” paste “wirthual/rpi-webiopi”.

Under ”Port mapping” click “+ map additional port” and map host port 82 to container port 8000.

Disable access control.

Go to “advanced container settings” and type “webiopi” in to the input labeled “Command”. This will be the start command that runs inside the webiopi container.

We have to give the container privileged access to the host so the webiopi app can access the gpio pins. Scroll down to the “advanced container settings”, click on tab “Runtime & Ressources” and enable “Privileged mode”.

If you whish the container to start after a reboot, go to the “Restart policy” tab and select “Unless stopped”.

Now we are finished and can deploy the container by clicking on “Deploy the container”.

After a while (~15min) you see the container is up and running.

Now you can navigate to http://rpi-docker-host:82 and access the gpio pins.

More infos:

#9 Wrapping it up

You see there is no need to develop complicated setup routines for getting your raspberry to work as you expect.

You can simply use arm compatible docker images to run you software stack. Find them by using the docker registry:

In a next tutorial (coming soon) we will evaluate how to deploy your code to a raspberry by using self (cross-)builded images or simply by copying the code and distribute it to a container.

Feel free to stalk my person or write me an email to