Flash HypriotOS to an SD card

You can install a docker server on the Raspberry Pi very easily by flashing an SD card with the HypriotOS image. This can be done with the following steps:

- Download HypriotOS from the Hypriot download page - Download Etcher - Use Etcher to flash the zip file to the SD card:

  1. Select the file you in step 1 (leftmost button). There is no need to extract the zip file, Etcher can use it directly.
  2. Select the disk to flash it to (middle button). Double check that it is your SD card! Sometimes Etcher auto-detects the drive already.
  3. Click 'Flash' (rightmost button) to finalize the process.
  4. When the process is completed, your SD card should come back called 'HypriotOS'.

- Set up WiFi (optional)

  1. On this SD card, there is a file called device-init.yaml.
    You can edit this file with a text editor to set your WiFi name and password.
    Optionally, you can also change the hostname of the docker server to something other than the default (black-pearl).
  2. The device-init.yaml is in /boot if you want to edit it on the Raspberry Pi.
      hostname: black-pearl
     # wifi:
     #   interfaces:
     #     wlan0:
     #       ssid: "MyNetwork"
     #       password: "secret_password"

Please note the space after :!

Do not forget to uncomment the lines by removing the '#' at the start of the lines.

Manual WiFi setup

If your WiFi doesn't work properly, you can also set the network settings yourself. Make sure you re-instate all the '#' in device-init.yaml.

Then instead edit the file wlan0 which is in /etc/network/interfaces.d/. You may have to create the file if it doesn't exist. For a static IP, you could use these settings:

allow-hotplug wlan0
auto wlan0
iface wlan0 inet static
  wpa-ssid "YOUR_SSID"

If you set up a static IP, make sure it is outside of your DHCP range. You can configure this in your router. A better alternative maybe to set up a static DHCP lease in your router, so the Raspberry Pi still gets an IP address automatically, but the router always gives it the same address.

The settings above are just an example. Change the settings to make them relevant to your network.

Etcher alternatives

If you weren't successful using Etcher for flashing your SD Card and are running Ubuntu, follow these instructions.

Find the IP address of the Raspberry Pi

Using your smartphone

To find the IP address I recommend the app Fing (Android / iOS).
This app can scan your local network for devices. If our raspberry pi successfully connected to your network, it should be in the list. Make a not of the IP address.

Using Linux or Mac

If you are running Linux or Mac, you can also try to ping the raspberry hostname you defined earlier followed by “.local”. If you didn't change it, it should be black-pearl.local.

Log in on the raspberry pi with ssh

To configure your raspberry pi, you should perform some commands on the command line. One way to do that, is to plug in a keyboard and HDMI monitor. But I think an easier way is to connect over SSH. SSH is a secure connection to a remote computer. You can use SSH to remotely log in on the command line of the pi, from your PC.

For HypriotOS (which you just installed on the Raspberry Pi), the default username is 'pirate' and the password is 'hypriot'.

Linux and Mac

An ssh client is installed by default on any Linux or MAC system. You can just this command on your PC to connect to the pi:

ssh pirate@

The command above is in case you found the IP address in your previous step. Adjust accordingly.


On Windows, you should download the ssh client PuTTY.

Using putty, you can connect to the Pi by entering the IP-address in the host field. Leave the port set to 22 and the connection type to SSH.

Log in with the username pirate and the password hypriot.

Configure your timezone

To make sure your future graphs reflect your localtime, make sure you change the timezone to yours:

$ sudo dpkg-reconfigure tzdata

Use then the date command to check the date and time.

Deploy the brewpi container

Get the latest raspbian based image brewpi image

docker pull brewpi/brewpi-raspbian

Deploy a new brewpi container. Modify the command below to to your liking, especially the port and the data location on the host (default is ~/brewpi-data). If you want to connect your BrewPi Spark over USB, check the section below.

docker run -d --name brewpi -p 80:80 -v ~/brewpi-data:/data -v /etc/timezone:/etc/timezone -v /etc/localtime:/etc/localtime --restart always brewpi/brewpi-raspbian

Let's break that down to explain each part.

Parameter Explanation
After starting the container, run it as daemon in the background.
--name brewpi
Name the new container brewpi, modify this you are running multiple brewpi containers.
-p 80:80
Map port 80 of the container to port 80 of the host. <br> If port 80 is in use, use a differnt port, for example 8000:80.
-v ~/brewpi-data:/data
Store data and settings in ~/brewpi-data on the host.
-v /etc/timezone:/etc/timezone -v /etc/localtime:/etc/localtime
Use timezone from the host.
--restart always
Start on boot and always restart the container when it stops.
The image that is used. Usebrewpi/brewpi-raspbian for the raspberry pi, brewpi/brewpi-ubuntu for x64/x86 systems.

Connecting the BrewPi Spark via USB

If you want to connect to the BrewPi Spark over USB, you need to pass an extra argument to the container to forward the usb device, before 'brewpi/brewpi-raspbian'.

Parameter Explanation
Make the serial port device /dev/ttyACM0 available in the container

The full command will then be:

docker run -d --name brewpi -p 80:80 -v ~/brewpi-data:/data -v /etc/timezone:/etc/timezone -v /etc/localtime:/etc/localtime --restart always --device=/dev/ttyACM0:/dev/ttyACM0 brewpi/brewpi-raspbian

Please note that you need to have the BrewPi Spark connected via USB when running this command, otherwise the ttyACM0 device will not be found.

Connecting the BrewPi Spark via WiFi

This step requires that you both configure the BrewPi Spark itself and your docker instance so it can find your controller on the network. Please follow this guide to configure both. Note that since you are running docker, expect the config.cfg to reside in ~/brewpi-data/settings/ or the folder you specified when ran your container.

Install the portainer web interface to manage docker containers

Portainer can make it easier to manage your running docker containers. You can install it with:

docker run -d -p 9000:9000 -v /var/run/docker.sock:/var/run/docker.sock --restart always --name portainer portainer/portainer

Use portainer to access the command line of the brewpi container

Try to load the portainer web interface: This IP address is where your rpi lives on your network and uses port 9000. Adjust accordingly. It will ask you to set an admin password. Pick a password and set it up. Use it to log in on the next page.

On the next page, choose to first option 'Manage the Docker instance where Portainer is running' and click the Connect button.

When you have logged in, you can see your running containers. In this case, there will be a brewpi and a portainer one. If you click on the published port, this will take you to the web interface.

If you click on the brewpi container, you can click on 'console' on the container page. This will drop you directly to the command line of the container if you need it.