The most recent version of this page is a draft.DiffThis version is outdated by a newer approved version.DiffThis version (2018/03/13 19:47) is a draft.
Approvals: 0/1
The Previously approved version (2017/08/20 08:08) is available.Diff

This is an old revision of the document!


We run BrewPi inside a Docker container to make it easier to:

  • Have 1-click deployment
  • Manage and isolate dependencies
  • Update with a few clicks
  • Support running multiple BrewPi servers on the same system

On the Raspberry Pi, we start with the latest Raspbian image and then install Docker. Then we use Docker to deploy and run a BrewPi container. To view and manage Docker containers, we'll also install portainer.

Install Raspbian

To get started we have to write Raspbian, the operating system for the Raspberry Pi, to an SD card. We can then boot from this SD card and log in to configure some basic settings.

To run without a monitor and keyboard (headless), you can download Raspbian Lite. It is smaller and lighter and ideal for a server. If you would like to have a full desktop environment with a GUI to use with a monitor, download the Desktop version. Both can be found here as a zip file:

The easiest tool to write the zip file to the SD card is Etcher.

To use Etcher to flash the zip file to the SD card:

  1. Select the file you downloaded 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! Most times Etcher auto-detects the drive already.
  3. Click 'Flash' (rightmost button) to finalize the process.

If Etcher doesn't work for you, here is an alternative guide for Ubuntu.

Configure WiFi and SSH to work at first boot

To ensure that you can log in remotely over WiFi, without having to connect a monitor and keyboard, you can create 2 files on the SD card that the Pi recognizes when it boots. After you have flashed the SD card, it should show up in your file manager as a partition named 'BOOT'. You might have to unplug and replug your SD card for it to show up.

Enable SSH

To enable the ssh server (so you can log in over the network), create an empty file with filename ssh (no extension) on the 'BOOT' partition.

Set up WiFi credentials

You can put a file on the BOOT partition with filename wpa_supplicant.conf. On boot, the Raspberry Pi will copy this file to `/etc/wpa_supplicant/wpa_supplicant.conf`, so it will be used by the system. The content of the file should be as below. You need to edit country, SSID and psk.

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev


After creating these two files, it is time to put the SD card in the Raspberry Pi and power it up. It will take some time to boot for the first time. You could plug in an HDMI monitor to see the progress.

Find the Raspberry Pi on your local network

It might not be necessary to find and remember the IP-address of your Raspberry Pi. It will register itself on the network as rasbperrypi.local. This is provided by the package avahi-daemon and it is called Zeroconf.

If the .local address doesn't work, you can use 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 on the list. Make a note of the IP address.

If you cannot find the Raspberry Pi on your network, you will have to plug in a monitor and keyboard to find out what is wrong. Or you can of course plug in a network cable instead of using WiFi.

Log in on the Raspberry Pi with ssh

SSH is a secure connection to a remote computer. You can use SSH to remotely login on the command line of the pi, from another system. It is much easier to use SSH than to use a keyboard, because you can copy and paste the commands below, instead of typing them.

From Linux or OSX

An ssh client is installed by default on Linux or OSX. You can use this command in a console window to connect to the pi:

ssh pi@raspberrypi.local

or by IP address ( is used here as an example):

ssh pi@

The default password is raspberry.

From a Windows PC

On Windows, you should download the ssh client PuTTY.

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

Log in with the username pi and the password raspberry.

Configure and install necessary packages

Once logged in, run raspi-config to configure your locale settings and time zone:

sudo raspi-config

Next, change the default password for the pi user:


Update the packages on the system:

sudo apt update & sudo apt dist-upgrade

Install Docker

curl -sSL | sh

Add the pi user to the docker group, so it can run docker commands:

sudo usermod -aG docker pi

Reboot the system to complete the setup:

sudo reboot

Deploy the Portainer docker image

Portainer is a web interface to manage your Docker containers. It runs in a docker container itself. Installing portainer is easy. Log in again with SSH. Pro tip: you can repeat previous commands by using the up arrow. You can autocomplete commands and paths using tab.

The command to deploy portainer is:

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

Portainer will now run on port 9000. Go to http://raspberrypi.local:9000, or http:<ip-address>:9000 in your web browser. ==== Deploy the brewpi container ==== Get the latest raspbian based image brewpi image <code> docker pull brewpi/brewpi-raspbian </code> 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. <code> 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 </code> Let's break that down to explain each part. ^ Parameter ^ Explanation ^ | <code>-d</code> | After starting the container, run it as daemon in the background. | | <code>–name brewpi</code> | Name the new container brewpi, modify this you are running multiple brewpi containers. | | <code>-p 80:80</code> | 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. | | <code>-v ~/brewpi-data:/data</code> | Store data and settings in ~/brewpi-data on the host. | | <code>-v /etc/timezone:/etc/timezone -v /etc/localtime:/etc/localtime</code> | Use timezone from the host. | | <code>–restart always</code> | Start on boot and always restart the container when it stops. | | <code>brewpi/brewpi-raspbian</code> | 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 ^ | <code>–device=/dev/ttyACM0:/dev/ttyACM0</code> | Make the serial port device /dev/ttyACM0 available in the container | The full command will then be: <code> 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 </code> 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. ==== 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.