diff --git a/README.md b/README.md index 76cf6bb..a641ec4 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ -OctoPrint containers [![Build Status](https://travis-ci.org/AmedeeBulle/octoprint-containers.svg?branch=master)](https://travis-ci.org/AmedeeBulle/octoprint-containers) -==================== +# OctoPrint containers [![Build Status](https://travis-ci.org/AmedeeBulle/octoprint-containers.svg?branch=master)](https://travis-ci.org/AmedeeBulle/octoprint-containers) # Contents + - [Introduction](#introduction) - [Balena.io setup](#balenaio-setup) @@ -20,10 +20,12 @@ OctoPrint containers [![Build Status](https://travis-ci.org/AmedeeBulle/octopri # Introduction + This is a Docker setup for [OctoPrint](https://octoprint.org/) on Raspberry Pi. It can be run with [balena.io](https://balena.io/) or as _Plain Docker_ on Raspbian. The setup is made of 3 containers: + - `octoprint`: runs the main [OctoPrint](https://octoprint.org/) application - `webcam`: runs the webcam streaming service (`mjpg-streamer`) - `haproxy`: exposes the above containers on http and https ports @@ -33,24 +35,27 @@ The build will use by default the latest [OctoPrint](https://octoprint.org/) rel This setup will run on any Raspberry Pi, however [OctoPrint](https://octoprint.org/) recommends a Raspberry Pi 3 or 3+. # Balena.io setup + Although it may seem complex at first, [balena.io](https://balena.io/) allows you to install and configure [OctoPrint](https://octoprint.org/) on a Pi in a few clicks. Also if you have multiple [OctoPrint](https://octoprint.org/) servers, they will be managed from a central place. For additional help and nice screenshots of the [balena.io](https://balena.io/) interface look at [Get started with Raspberry Pi 3 and Python](https://docs.balena.io/learn/getting-started/raspberrypi3/python/) on the [balena.io](https://balena.io/) site. ## Install BalenaOS on your Pi + 1. Create an account at [balena.io](https://balena.io/) and sign in 1. Add your public SSH key to your [balena.io](https://balena.io/) profile 1. On [balena.io](https://balena.io/), create an "Application" for managing your Pi. Choose "Raspberry Pi 3" as Device Type. 1. Add a Device to your Application. - - Configure wifi here if your Pi is wireless. - - Download the BalenaOS image for your Pi. + - Configure WiFi here if your Pi is wireless. + - Download the BalenaOS image for your Pi. 1. 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. 1. 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: @@ -61,110 +66,143 @@ WEBCAM_START | `true` | Start the webcam streaming at boot t WEBCAM_INPUT | `input_raspicam.so -fps 5` | The input plugin for [`mjpg-streamer`](https://github.com/jacksonliam/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](https://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](https://gitforwindows.org/) or something similar). Clone this repository: + +```shell +git clone https://github.com/AmedeeBulle/octoprint-containers.git +cd octoprint-containers/ ``` -$ git clone https://github.com/AmedeeBulle/octoprint-containers.git -$ cd octoprint-containers/ -``` + Add the address of your [balena.io](https://balena.io/) repository. This command is displayed in the top-left corner of your application dashboard on the web site and looks like: + +```shell +git remote add balena @git.balena.io:/.git ``` -$ git remote add balena @git.balena.io:/.git -``` + Push the code to [balena.io](https://balena.io/): + +```shell +git push balena master ``` -$ git push balena master -``` + This will trigger a build on the [balena.io](https://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](https://octoprint.org/) server will be ready to go! For future updates, you simply need to pull the new code and push it back to [balena.io](https://balena.io/) and your device will be updated! -``` -$ git pull origin master -$ git push balena master + +```shell +git pull origin master +git push balena master ``` # Docker setup + If you do not want to use the [balena.io](https://balena.io/) services, you can run the exact same configuration directly on your Raspberry Pi. ## Prepare the Raspberry Pi -Download and install [Raspbian Stretch Lite](https://www.raspberrypi.org/downloads/raspbian/) to your Pi (Follow the instructions from the Foundation). + +Download and install [Raspbian Buster Lite](https://www.raspberrypi.org/downloads/raspbian/) 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`: + +```shell +apt-get update +apt-get install git curl python-pip +curl -sSL https://get.docker.com | sh +pip install 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: + +```shell +usermod -a -G docker ``` -# usermod -a -G docker -``` + 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/ + +```shell +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: + +```shell +docker-compose pull ``` -$ docker-compose pull -``` -__If you are not using a Raspberry Pi 3__: _multiarch_ build does not work properly on ARM variants (See https://github.com/moby/moby/issues/34875 ). + +__If you are not using a Raspberry Pi 3__: _multiarch_ build does not work properly on ARM variants (See Moby issue [34875](https://github.com/moby/moby/issues/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 + +```shell +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: + +```shell +docker-compose build ``` -$ 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 customise your setup, create a file named `.env` with the environment variables described in the [balena.io](https://balena.io/) section. You can use the file `.env-distr` as template. + +To customize your setup, create a file named `.env` with the environment variables described in the [balena.io](https://balena.io/) section. You can use the file `.env-distr` as template. __Important__: in `docker-compose.yml` uncomment the following line: -``` + +```yaml - /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](https://octoprint.org/) user interface. Run the [OctoPrint](https://octoprint.org/) server: + +```shell +docker-compose up ``` -$ 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: + +```shell +docker-compose up -d ``` -$ 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 + +```shell +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](https://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](https://octoprint.org/)! @@ -174,18 +212,23 @@ At first run, the `haproxy` container will generate a self-signed SSL certificat 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](https://balena.io/): select 'Purge Data' in the Device Menu -- _Plain Docker_: run -``` +- _Plain Docker_: run + +```shell 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](https://balena.io/): click on the 'Restart' icon in the Device Dashboard -- _Plain Docker_: run -``` +- _Plain Docker_: run + +```shell docker-compose down docker-compose up -d ```