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:29) 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.

Basic installation of 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.

Making WiFi and SSH 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.

Linux and Mac

An ssh client is installed by default on any Linux or MAC system. 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.


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.

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.