Step by step guide to installing OctoPrint on RHEL-like distributions
Disclaimer
WARNING
The instruction provided in this guide are provided as is. They were performed on VMs or real computers so they should work on newly installed computer. If your computer already runs one of the target distributions, your mileage may vary, although, you're most likely to run into already installed packages than anything else.
Also, the guide is valid at the time of writing (September 14th, 2021). Revisions and corrections may be carried out as long as I can afford to, but it may become obsolete. Regarding Fedora, release cycle is 6-month long, so if the last modified date is more than a year ago, you may run into commands that won't work as intended. CentOS based distributions follow a longer release cycle and the instructions should be valid until the EOL date of the release.
Contents
- Target distributions and versions
- What's covered in the guide, and what's not
- Thanks and contributors
- Installing required packages and activating SSH
- Setting up the OctoPrint instance
-
Optional: Setting up webcam stream
6.a. Using mjpg-streamer
6.b. Using µstreamer
6.c. Adjusting firewall rules and streaming test -
Optional: Using a reverse proxy to make OctoPrint available on port 80 (default HTTP port)
7.a. Preparing the OctoPrint configuration and adjusting firewall rules
7.b. Using HAProxy
7.c. Using Apache HTTPd and mod_proxy -
Create the relevant service files and make services start on boot
8.a. Octoprint service
8.b. Optional: Webcam streaming service
8.c. Optional: Reverse Proxy - OctoPrint first run wizard configuration
- Changelog
1. Target distributions and versions
At the time of writing, this guide is intended and works for the following distributions and versions :
Fedora
Workstation and Server edition: version 34
Where to get it: https://getfedora.org
CentOS Linux and CentOS Stream
Linux: version 8.x
Stream: version 8
Where to get it: https://www.centos.org/
AlmaLinux
Version: 8.x
Where to get it: https://almalinux.org/
RockyLinux
Version: 8.x
Where to get it: https://rockylinux.org/
The instruction provided in this guide should work on other distributions based on RHEL (Red Hat Enterprise Linux) or CentOS, but have not been tested, so again, your mileage may vary... Please bear in mind that setting up a VM and testing (and sometimes adapting) the commands and steps carried out in this guide is time-consuming, that's why it's limited to the distributions stated above.
2. How to read this guide? What's covered in the guide, and what's not?
How to read this guide?
Formatting info:
-
Blockquotes denotes text that is important to read. These may seem long, but there are some crucial information in those texts, please read them.
- Commands that you need to run will appear in code blocks such as these, one command per line:
cd /opt/octoprint mv source destination systemctl restart octoprint.service - Unless otherwise specified the commands apply for all the distributions and versions listed here. If any distribution or version needs a specific command, it will appear this way:
Fedora 34
command specific to Fedora 34Other distributions and versions
common command - File contents will also be shown in code blocks, with the filename between brackets ([]), as shown below:
[filename] File contents go here and may spread many lines - If a specific version or distributions needs specific file contents, those will be shown the same way specific commands are.
Assumptions made during the guide:
-
Commands throughout this guide will make heavy use of
sudoas configuration files are usually not editable by an unprivileged user. Make sure the user you use to run these commands can usesudo, by making sure that the user belongs to thewheelgroup. -
OctoPrint will be installed to the
/opt/octoprintdirectory. Should you wish to install it to another directory, replace with the full path in command where it appears. There should be enough space to store your data in this directory. Ideally the directory should be a mount point for a separate partition on the hard drive, so that OctoPrint's data does not clutter the system, and so that you may easily monitor space taken up by its files. -
Any
<IP-ADDRESS>placeholder occurring in commands or file contents should be replaced with the computer's IP address. You can determine this address by running the following commandip a s -
An unprivileged user will be created, using the username
octoprint. If a user already has that username, either choose another username such asoctoserverand adapt the commands user throughout this guide, or make sure that the already existing user belongs only to theoctoprint,tty,dialoutandvideogroups, has its shell set to/sbin/nologin, and its home directory set to/opt/octoprint. -
Any
<WEBCAM-ID>placeholder occurring in commands or file contents should be replaced with the appropriate webcam ID. How to find this ID will be covered in Optional: Setting up webcam streaming.
What does this guide covers and what it doesn't:
This guide supposes that you already have a working installation of any of the distribution listed in the Target distributions and versions section. This guide won't explain how to install those distributions on any computer. There are far better written guides on the Internet that already serve that purpose. This guide also expects you to have more than a basic understanding of how to run commands in a Linux, and mostly a Command Line Interface environment, especially, you need to know how to edit files, even privileged ones. This guide also expects you to have a priviledged user on the system, a user (whose username is notoctoprint) that is able to run thesudocommand. Alternatively, you may use therootaccount to carry out commands, although this is not recommended.This guide will cover the installation of an OctoPrint instance, starting at the mot basic installation possible. This guide will not cover the installation of any other plugin or software than described in the Contents. Some steps are completely optional and not completing these steps will not put you in a state where the OctoPrint instance is not reachable. The steps are supposed to be followed in the order they are written in this guide. Failing to complete a step may alter how the following step should be carried out, so please follow the steps in their intended order. Obviously, steps that are advertised as Advanced require a more thorough understanding of how a Linux, and more particularly RHEL-like Linux environment works. Do not attempt to follow them if you don't feel up to it. You'll have a working OctoPrint instance even if you do not complete these steps.
This guide won't explain in details what the commands are doing, other than the explanations given. This is why you are expected to have a basic understanding of Linux and also RHEL. This guide assumes that you know how to connect to the computer through SSH (i.e. using PuTTY in Windows)
GUI or not GUI?
This guide will work whether you would like to install a Graphical User Interface (ie GNOME desktop, KDE, LXDE...) or not. All the instructions and commands given in this guide can be run over SSH. As a matter of fact, this guide is even intended to work on headless systems, meaning without screen, keyboard and mouse. Should you want to use graphical equivalents to the commands given, this guide assumes that you now which utilities to substitute for each command. I will not tell you which graphical software may accomplish what each command does. That is entirely up to you, since there are a lot of desktop environments, each with its specific utilities to carry out specific tasks, and I can only know so much...
Should you have any questions concerning the contents of the guide, you may ask them below, I'll try to answer it to the best of my knowledge. Other users may also answer the question. Please keep the questions to the subject. I will not answer questions regarding any other distributions and versions than those listed here. Other users having knowledge about the distribution you're using may answer your question. Please also refer to the specific section of this guide your question is about, that will help us better answer your question. Also, should you encounter an error running a specific command in the guide, please indicate, in addition to the section, the command you're trying to run, and also the error that was encountered. This will also help us solve your problem more quickly.
Concerns about security
This guide expects you to have a secured LAN to which the computer connects. Should some ports be opened in the firewall (
3. Thanks and contributors
This guide is heavily adapted from the guide named Setting up OctoPrint on a Raspberry Pi running Raspbian or Raspberry Pi OS by @foosel.
Contributors to this guide:
- @SwHawk : author
Should you want to add instructions about setting up Octoprint on another distribution not listed here, feel free to write the needed instruction while following the steps in this guide. Should you want to add instructions for other software that can be part of this guide, please also make sure that the software is available for the target distributions and versions, or provide instruction to compile them as a last resort. Please also test those software on all the target distributions and versions. You can then send those instruction in a PM mentioning the title of this guide, and I'll include them, and list you here as a contributor. Please bear in mind that you would be responsible for answering questions pertaining to the section you've written.
4. Installing required packages and activating SSH
Making sure the system is up to date
Before installing any packages, or proceeding any further, you should update the system using the following command:
sudo dnf --refresh upgrade
And then reboot the system, in case a kernel update took place:
systemctl reboot
Activating SSH
Only the Fedora Workstation Edition doesn't enable SSH access right after the installation process. To enable SSH access, you need to run the following command:
Fedora Workstation Edition
systemctl enable --now sshd.service
Install required packages
sudo dnf install python3-{pip,devel,setuptools,wheel}
Create the octoprint user and home directory
The following command will create the octoprint user with the needed groups and security restrictions:
sudo useradd -d /opt/octoprint -G tty,dialout,video -M -r -s /sbin/nologin -U octoprint
Then the following commands will create the /opt/octoprint directory and assign it the right owner and permissions:
sudo mkdir /opt/octoprint
sudo chown octoprint:octoprint /opt/octoprint
5. Setting up the OctoPrint instance
Python3 virtual environment setup
The following commands will set up a Python virtual environment in the /opt/octoprint directory:
cd /opt/octoprint
sudo -u octoprint python3 -m venv .
sudo -u octoprint bin/pip --no-cache-dir install --upgrade pip
OctoPrint installation
The followin command will install OctoPrint inside the virtual environment:
sudo -u octoprint bin/pip --no-cache-dir install octoprint
At this moment, the OctoPrint instance will only reachable from the computer it's installed on due to firewall configuration. In order to be able to access it from your network, we'll need to tell the firewall to open port 5000. To do so, a new service will be defined inside the firewall, using the following commands:
sudo firewall-cmd --permanent --new-service=octoprint
sudo firewall-cmd --permanent --service=octoprint --add-port=5000/tcp
sudo firewall-cmd --reload
sudo firewall-cmd --permanent --add-service=octoprint
sudo firewall-cmd --add-service=octoprint
Verify OctoPrint starts
The following command will start the OctoPrint instance:
sudo -u octoprint bin/octoprint serve
You should then see something along those lines showing up on the terminal:
[user@localhost octoprint]$ sudo -u octoprint bin/octoprint serve
2021-09-13 17:39:17,979 - octoprint.startup - INFO - ***************************
2021-09-13 17:39:17,980 - octoprint.startup - INFO - Starting OctoPrint 1.6.1
2021-09-13 17:39:17,980 - octoprint.startup - INFO - ***************************
You can try to access the OctoPrint instance by opening a browser and going to http://<IP-ADDRESS>:5000/ and you should be greeted with OctoPrint's UI and first run wizard. As for now, you should not complete the First Run Wizard, as the configuration is not complete. You can hit ctrl + c to exit the process. Should you want to set up a webcam or a reverse proxy, proceed to the relevant sections. Otherwise please proceed to the 8. Create the relevant service files and make services start on boot section.
6. Optional: Setting up webcam stream
Should you like to monitor your prints, you can plug in a USB webcam. Whichever software you wish to install to stream the camera feed, you'll need to install additional packages using the following commands:
Fedora
sudo dnf install make gcc gcc-c++ git libjpeg-turbo-devel v4l-utils
Other distributions and versions
sudo dnf install make gcc gcc-c++ git libjpeg-turbo-devel
Should you like to create timelapses from your webcam, you'll need FFmpeg. Although it is not in the official repositories for licensing reasons, the RPMFusion repositories do have them. We'll need to enable them on your system, using the following commands:
Fedora
34
sudo dnf install https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
sudo dnf install ffmpeg
Other distributions and versions
sudo dnf install --nogpgcheck https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
sudo dnf install --nogpgcheck https://mirrors.rpmfusion.org/free/el/rpmfusion-free-release-8.noarch.rpm https://mirrors.rpmfusion.org/nonfree/el/rpmfusion-nonfree-release-8.noarch.rpm
sudo dnf config-manager --enable powertools
sudo dnf install ffmpeg
We'll also need to find out the ID of your webcam. In order to do this, you need to inspect the output of the following command, after the camera was plugged in:
ls /dev/v4l/by-id
For example, on the computer I have OctoPrint set up, and two webcams are plugged, I see the following output:
[silver@octoprint octoprint]$ ls /dev/v4l/by-id
usb-GENERAL_GENERAL_WEBCAM_JH0809_20201204_v002-video-index0 usb-Microsoft_Microsoft®_LifeCam_HD-5000-video-index0
usb-GENERAL_GENERAL_WEBCAM_JH0809_20201204_v002-video-index1 usb-Microsoft_Microsoft®_LifeCam_HD-5000-video-index1
Each webcam offers two peripherals to the OS, and from experience, the index0 peripheral give the actual video. The MS camera is the one pointing to the 3D printer, so the ID for this webcam is usb-Microsoft_Microsoft®_LifeCam_HD-5000-video-index0. I would need to replace <WEBCAM-ID> by usb-Microsoft_Microsoft®_LifeCam_HD-5000-video-index0.
Now is the time to choose between the two software offering streaming capabilities. You need to complete either step 6.a. or step 6.b., not both, or you'll end up with a non-functional stream.
6.a. Using mjpg-streamer
Since there are no packages in the official repositories, we need to compile this from source. To do so, we need to actually download the sources using git. The following commands will install additional required packages, download the sources, compile them, and place the resulting binaries in a specific place known by the OS.
sudo dnf install ImageMagick cmake
cd ~
git clone https://github.com/jacksonliam/mjpg-streamer.git
cd mjpg-streamer/mjpg-streamer-experimental/
make
sudo make install
If all the commands ran successfully, you can now proceed to 6.c. Adjusting firewall rules and streaming test.
6.b. Using µstreamer
Since there are no packages in the official repositories, we need to compile this from source. To do so, we need to actually download the sources using git. The following commands will install additional required packages, download the sources, compile them, and place the resulting binaries in a specific place known by the OS.
sudo dnf install libevent-devel libbsd-devel
cd ~
git clone https://github.com/pikvm/ustreamer.git
cd ustreamer
make
sudo make install
If all the commands ran successfully, you can now proceed to 6.c. Adjusting firewall rules and streaming test.
6.c. Adjusting firewall rules and streaming test
Adusting the firewall rules
For now, the webcam stream would only be accessible from the computer running OctoPrint. To make accessible to the whole network we need to open an additional port in the firewall. Should you want to proceed to the Optional: Using a reverse proxy to make OctoPrint available on port 80 (default HTTP port) step afterwards, following these instructions is not needed, and you should directly proceed to the streaming test section. Otherwise, please run the following commands to open the port needed for webcam streaming
sudo firewall-cmd --permanent --service=octoprint --add-port=8080/tcp
sudo firewall-cmd --reload
Testing the webcam stream
Depending on whether you installed mjpg-streamer or µstreamer, please follow the appropriate instructions below
mjpg-streamer
You need to run the following command to start the streaming process:
sudo -u octoprint /usr/local/bin/mjpg_streamer -i 'input_uvc.so -d /dev/v4l/by-id/<WEBCAM-ID>' -o 'output_http.so -p 8080 -l 0.0.0.0 -n'
The program should output lines to the terminal similar to this:
[silver@octoprint mjpg-streamer-experimental]$ sudo -u octoprint /usr/local/bin/mjpg_streamer -i 'input_uvc.so -d /dev/v4l/by-id/<WEBCAM-ID>' -o 'output_http.so -p 8080 -l 0.0.0.0 -n'
MJPG Streamer Version: git rev: 310b29f4a94c46652b20c4b7b6e5cf24e532af39
i: Using V4L2 device.: /dev/video0
i: Desired Resolution: 1280 x 720
i: Frames Per Second.: -1
i: Format............: JPEG
i: TV-Norm...........: DEFAULT
UVCIOC_CTRL_ADD - Error at Pan (relative): Inappropriate ioctl for device (25)
UVCIOC_CTRL_ADD - Error at Tilt (relative): Inappropriate ioctl for device (25)
UVCIOC_CTRL_ADD - Error at Pan Reset: Inappropriate ioctl for device (25)
UVCIOC_CTRL_ADD - Error at Tilt Reset: Inappropriate ioctl for device (25)
UVCIOC_CTRL_ADD - Error at Pan/tilt Reset: Inappropriate ioctl for device (25)
UVCIOC_CTRL_ADD - Error at Focus (absolute): Inappropriate ioctl for device (25)
UVCIOC_CTRL_MAP - Error at Pan (relative): Inappropriate ioctl for device (25)
UVCIOC_CTRL_MAP - Error at Tilt (relative): Inappropriate ioctl for device (25)
UVCIOC_CTRL_MAP - Error at Pan Reset: Inappropriate ioctl for device (25)
UVCIOC_CTRL_MAP - Error at Tilt Reset: Inappropriate ioctl for device (25)
UVCIOC_CTRL_MAP - Error at Pan/tilt Reset: Inappropriate ioctl for device (25)
UVCIOC_CTRL_MAP - Error at Focus (absolute): Inappropriate ioctl for device (25)
UVCIOC_CTRL_MAP - Error at LED1 Mode: Inappropriate ioctl for device (25)
UVCIOC_CTRL_MAP - Error at LED1 Frequency: Inappropriate ioctl for device (25)
UVCIOC_CTRL_MAP - Error at Disable video processing: Inappropriate ioctl for device (25)
UVCIOC_CTRL_MAP - Error at Raw bits per pixel: Inappropriate ioctl for device (25)
o: www-folder-path......: disabled
o: HTTP TCP port........: 8080
o: HTTP Listen Address..: 0.0.0.0
o: username:password....: disabled
o: commands.............: disabled
The UVCIOC_CTRL_ADD - Error at lines do not indicate that the streaming process didn't start, but rather that the camera doesn't support setting the specified control. Should mjpg-streamer fail to start, you shouldn't see the lines starting with o: . Otherwise you should consider your test to be successfull. You can now hit ctrl+c to exit the mjpg-streamer software.
µstreamer
You need to run the following command to start the streaming process
sudo -u octoprint /usr/local/bin/ustreamer -d /dev/v4l/by-id/<WEBCAM-ID> -m MJPEG -s 0.0.0.0 -p 8080
µstreamer should then output something similar to the terminal:
[silver@octoprint ustreamer]$ sudo -u octoprint /usr/local/bin/ustreamer -d /dev/v4l/by-id/<WEBCAM-ID> -m MJPEG -s 0.0.0.0 -p 8080
-- INFO [2000164.132 main] -- Using internal blank placeholder
-- INFO [2000164.133 main] -- Listening HTTP on [0.0.0.0]:8080
-- INFO [2000164.133 stream] -- Using V4L2 device: /dev/v4l/by-id/<WEBCAM-ID>
-- INFO [2000164.133 stream] -- Using desired FPS: 0
-- INFO [2000164.133 http] -- Starting HTTP eventloop ...
==============================================================================================================================================================
-- INFO [2000164.230 stream] -- Device fd=8 opened
-- INFO [2000164.230 stream] -- Using input channel: 0
-- INFO [2000164.235 stream] -- Using resolution: 640x480
-- INFO [2000164.235 stream] -- Using pixelformat: MJPEG
-- INFO [2000164.240 stream] -- Using HW FPS: 0 -> 30 (coerced)
-- ERROR [2000164.240 stream] -- Device does not support setting of HW encoding quality parameters
-- INFO [2000164.240 stream] -- Using IO method: MMAP
-- INFO [2000164.241 stream] -- Requested 5 device buffers, got 5
-- INFO [2000164.477 stream] -- Capturing started
-- INFO [2000164.477 stream] -- Switching to HW encoder: the input is (M)JPEG ...
-- INFO [2000164.477 stream] -- Using JPEG quality: encoder default
-- INFO [2000164.477 stream] -- Creating pool JPEG with 1 workers ...
-- INFO [2000164.477 stream] -- Capturing ...
The ERROR line refers to problems with the webcam, but those do not prevent camera streaming. The important line is the last one which ends in Capturing ...
This is a YAML file, you should use two spaces when adding a level of identation, not tabs! The file should then look like: