OctoPrint containers

Contents

• Introduction
• Balena.io setup
  • Install BalenaOS on your Pi
  • Configure your OctoPrint device
  • Install the software on the Device
• Docker setup
  • Prepare the Raspberry Pi
  • Get the containers
    • Option 1: Download the containers
    • Option 2: Re-Build the containers
  • Configure and run the OctoPrint server
  • Updates
• First run
• Note about persistence
• Multiple printers

Introduction

This is a Docker setup for OctoPrint on Raspberry Pi.
It can be run with balena.io or as Plain Docker on Raspbian.

The setup is made of 3 containers:

• octoprint: runs the main OctoPrint application
• webcam: runs the webcam streaming service (mjpg-streamer)
• haproxy: exposes the above containers on http and https ports

The build will use by default the latest OctoPrint release, this can be overridden by changing the release argument in the docker-compose.yml file.

This setup will run on any Raspberry Pi, however OctoPrint recommends a Raspberry Pi 3 or 3+.

Balena.io setup

Although it may seem complex at first, balena.io allows you to install and configure OctoPrint on a Pi in a few clicks.
Also if you have multiple OctoPrint servers, they will be managed from a central place.

For additional help and nice screenshots of the balena.io interface look at Get started with Raspberry Pi 3 and Python on the balena.io site.

Install BalenaOS on your Pi

1. Create an account at balena.io and sign in
2. Add your public SSH key to your balena.io profile
3. On balena.io, create an "Application" for managing your Pi.
   Choose "Raspberry Pi 3" as Device Type.
4. Add a Device to your Application.
   • Configure WiFi here if your Pi is wireless.
   • Download the BalenaOS image for your Pi.
5. Follow the instructions to write the OS on your SD-Card and boot your Pi.
   After a while your Pi will appear in your Application Dashboard.
6. If you like you can change the name of your device.

Configure your OctoPrint device

The Environment Variables menu "E(x)" allows you to add variables to configure the device for your usage.

You can add the following variables:

Name	Default	Description
WEBCAM_START	true	Start the webcam streaming at boot time. Use false if you have no webcam or want to start it from the OctoPrint menu
WEBCAM_INPUT	input_raspicam.so -fps 5	The input plugin for mjpg-streamer. Default is for the Raspberry Pi camera, see the documentation for others. Example for an USB webcam: input_uvc.so -d /dev/video0 -r 640x480 -fps 5.

Install the software on the Device

The device is now ready, we need to push the containers through balena.io.
The following commands need to be executed from the terminal on your local machine -- not on the Raspberry Pi!
(On Windows, use Git BASH or something similar).

Clone this repository:

git clone https://github.com/AmedeeBulle/octoprint-containers.git
cd octoprint-containers/

Add the address of your balena.io repository. This command is displayed in the top-left corner of your application dashboard on the web site and looks like:

git remote add balena <USERNAME>@git.balena.io:<USERNAME>/<APPNAME>.git

Push the code to balena.io:

git push balena master

This will trigger a build on the balena.io servers. If all goes well it will finish with a nice unicorn 🦄 ASCII art.
Your Raspberry Pi will download and run the containers automatically; after that your OctoPrint server will be ready to go!

For future updates, you simply need to pull the new code and push it back to balena.io and your device will be updated!

git pull origin master
git push balena master

Docker setup

If you do not want to use the balena.io services, you can run the exact same configuration directly on your Raspberry Pi.

Prepare the Raspberry Pi

Download and install Raspbian Buster Lite to your Pi (Follow the instructions from the Foundation).
Although it will work with the full Desktop environment, I strongly recommend the Lite version.

As root, install git, docker and docker-compose:

apt-get update
apt-get install git curl python-pip
curl -sSL https://get.docker.com | sh
pip install docker-compose

Ensure your linux user (pi or whatever you choose) is in the docker group:

usermod -a -G docker <YourLinuxUser>

At this point you need to completely logout and re-login to activate the new group.

From here, you don't need root access anymore.

Clone this repository:

git clone https://github.com/AmedeeBulle/octoprint-containers.git
cd octoprint-containers/

Get the containers

You have 2 options here: download the pre-build containers or re-build them.

Option 1: Download the containers

This is the easiest and fastest way. The pull command will download the containers from the Docker Hub:

docker-compose pull

If you are not using a Raspberry Pi 3: multiarch build does not work properly on ARM variants (See Moby issue 34875).
For older Raspberry Pi you need to amend the docker-compose files to pull the correct images:

sed -e 's/\(image:.*\)/\1:arm32v6-latest/' -i.orig docker-compose.yml

Option 2: Re-Build the containers

If for whatever reason you want to re-build the containers on your Pi, run:

docker-compose build

If you are not using a Raspberry Pi 3: copy the .env-distr to .env and select you Raspberry Pi version.

Configure and run the OctoPrint server

To customize your setup, create a file named .env with the environment variables described in the balena.io section. You can use the file .env-distr as template.

Important: in docker-compose.yml uncomment the following line:

      - /run/dbus:/host/run/dbus

If you don't do that, you won't be able to restart or shut down you Pi from the OctoPrint user interface.

Run the OctoPrint server:

docker-compose up

This will start the containers and remain attached to your terminal. If everything looks good, you can cancel it and restart the service in detached mode:

docker-compose up -d

This will keep he containers running, even after a reboot.

Updates

To update your setup with a newer version, get the latest code and containers and restart the service:

docker-compose down
git pull origin master
docker-compose pull # or build
docker-compose up -d

First run

For a Plain Docker setup, you know the IP address of your Pi; if you run balena.io, you will find the address in the application console.

Point your browser to the IP address of your Raspberry Pi and enjoy OctoPrint!

At first run, the haproxy container will generate a self-signed SSL certificate, so the service will be available on both http and https ports. If you want to share your printer with the world, only expose the https port...

Enjoy!

Note about persistence

All working files (configuration, G-Code, time-lapses, ...) are stored in the octoprint_vol Docker volume, so they won't disappear unless you explicitly destroy the volume.
If you really need/want to destroy the volume and re-start from scratch:

• balena.io: select 'Purge Data' in the Device Menu
• Plain Docker: run

docker-compose down -v

The same applies to the containers themselves: they won't be destroyed by default even if you reboot the Pi. To remove existing container and re-create them:

• balena.io: click on the 'Restart' icon in the Device Dashboard
• Plain Docker: run

docker-compose down
docker-compose up -d

By doing this, you will loose any change made to the code, in particular if you installed plugins you will have to re-install them (but their configuration will be preserved).

Multiple printers

Although driving multiple printers from the same Raspberry Pi is possible, it might lead to performance issues. This setup is nevertheless easy to achieve with the plain Docker setup.
It is a good solution if:

• You have a powerful Raspberry Pi
• You have multiple printers but use only one at a time

You can run any number of instances of this container stack by using a different project name and a different .env file.
The docker-compose-multi.sh convenience script is provided to simplify operations.

Assuming you already have a running instance, to add a new one simply copy the .env-extra-distr sample file to .env-<printer name>, review the configuration parameters and start the instance with ./docker-compose-multi.sh <printer name> up -d.

Main points of attention:

• Do not configure more than one Raspberry Pi camera!
  (There is no limitation on the number of USB cameras)
• Ensure all instances have their own unique HTTP and HTTPS ports.

Sample session:

# Start the main instance
$ docker-compose up -d
Creating network "octoprint_default" with the default driver
Creating octoprint_octoprint_1 ... done
Creating octoprint_webcam_1    ... done
Creating octoprint_haproxy_1   ... done
$ docker-compose ps
        Name                       Command               State                    Ports
---------------------------------------------------------------------------------------------------------
octoprint_haproxy_1     /usr/bin/entry.sh /opt/hap ...   Up      0.0.0.0:443->443/tcp, 0.0.0.0:80->80/tcp
octoprint_octoprint_1   /usr/bin/entry.sh /opt/oct ...   Up      5000/tcp
octoprint_webcam_1      /usr/bin/entry.sh /opt/web ...   Up      5200/tcp, 8080/tcp

# Start an additional instance for the "extra" printer:
$ cp .env-extra-distr .env-extra
$ vi .env-extra
$ ./docker-compose-multi.sh extra up -d
Creating network "extra_default" with the default driver
Creating volume "extra_octoprint_vol" with default driver
Creating extra_webcam_1    ... done
Creating extra_octoprint_1 ... done
Creating extra_haproxy_1   ... done
$ ./docker-compose-multi.sh extra ps
      Name                     Command               State                      Ports
--------------------------------------------------------------------------------------------------------
extra_haproxy_1     /usr/bin/entry.sh /opt/hap ...   Up      0.0.0.0:8443->443/tcp, 0.0.0.0:8080->80/tcp
extra_octoprint_1   /usr/bin/entry.sh /opt/oct ...   Up      5000/tcp
extra_webcam_1      /usr/bin/entry.sh /opt/web ...   Up      5200/tcp, 8080/tcp

Notes:

• As you can see in the above output, instances use a different network namespace as well as a different volume for storing data, so they are completely separated and independent.
• Depending on when your printers / cameras are detected they might get different device names on your Raspberry Pi... Always check that you are driving the right printer!