This version (2019/03/16 16:51) is a draft.
Approvals: 0/1
The Previously approved version (2018/05/10 00:07) is available.Diff

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 raspberrypi.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 password, locale settings and time zone:

sudo raspi-config

Update the packages on the system:

sudo apt-get update && sudo apt-get dist-upgrade

Install Docker

curl -fsSL -o && 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 pull portainer/portainer
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.

It will ask you to set an admin password when you first access it.

On the container tab, you can see all the docker containers that are running. At this point, it will be only the container that runs portainer.

From this page, you can create, delete or recreate containers. You can also click on 'console' to run commands inside the container.

Finally click on 'endpoints' in the left menu. Click on the only endpoint which is called 'primary' or 'local'. In the public IP field, enter raspberrypi.local or the IP address of the pi. If you omit this step, clicking on exposed ports of a container will link to instead of raspberrypi.local:80, which will not work.

Deploy the BrewPi container

Now we are ready to deploy a BrewPi container. This container will run the BrewPi web interface and the BrewPi Python script that communicates with the BrewPi Spark.

The container will store your brewing data and settings outside of the container, so you can safely delete and recreate the container without losing data. This is done by creating a mapped volume. In the command below, the ~/brewpi-data on the raspberry pi host is mapped to /data in the container.

The container is started with -d, so it runs as a daemon in the background. If you run into trouble, omit -d to see where it errors.

The container exposes 2 ports, port 80 and port 81. The only difference is that port 81 asks for a username and password.

If you want to forward a port on your router, so you can access it from outside of your home network, only forward port 81.

docker pull brewpi/brewpi-raspbian
docker run -d --name brewpi --privileged -p 80:80 -p 81:81 -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.
Run with elevated permissions to access serial ports that are present when the container starts.
-p 80:80
Map port 80 of the container to port 80 of the host. <br> If port 80 is in use, use a different port, for example 8000:80.
-p 81:81
Map port 81 of the container to port 81 of the host.
-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 and time 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.

Please note that you need to have the BrewPi Spark connected via USB when the container starts for it to be available to the container. In the web interface, you can select the serial number (for USB) or enter the IP address of the Spark to connect.

Change the password for port 81

The default login details are username brewer and password brewpi. To change the password, you can run:

sudo apt install apache2-utils
sudo htpasswd -bc ~/brewpi-data/settings/brewpi.htpasswd username password

Replace username and password with your desired user name and password.

If you run the command inside your container instead of on the host, the command should be:

sudo htpasswd -bc /data/settings/brewpi.htpasswd username password


If you get an error about a conflict with an existing container (see below), you can remove the old container or use another name for the new one.

docker: Error response from daemon: Conflict. The container name “/brewpi” is already in use by container “e863…”. You have to remove (or rename) that container to be able to reuse that name.
See ‘docker run --help’.

To remove the existing container named 'brewpi', run:

docker stop brewpi
docker rm brewpi

To view all containers, run the command below or use portainer.

docker ps -a

Go to the BrewPi web interface and connect to the Spark

If you didn't change the default port, you can access the BrewPi web interface at http://raspberrypi.local.

Click 'Start script', if it isn't already running.

Finally, go to the maintenance panel and fill in the field for connection to let the script know where it can find your BrewPi Spark.

If you want to connect to the Spark over Wifi, set the drop-down menu to 'IP address' and enter the IP address that is displayed on the LCD of your BrewPi Spark.

Updating the BrewPi container

The easiest way to update the container is let portainer re-create it. Browse to the BrewPi container and click 'recreate'. Leave 'pull latest image' ticked.

If you do this, you will lose any changes you made inside the container. Only the BrewPi settings and data that are stored outside of the container are kept.

You can also stop the container and create a new one before you delete the old container. Just make sure that each container needs to have a unique name and that running containers cannot use the same port on the host.