octoprint_deploy turns one Raspberry Pi into a fleet of print servers

What the script actually installs

The project describes itself as providing a bash script for quickly deploying multiple OctoPrint instances on a single computer, and for Linux systems such as Ubuntu and Fedora it will also install OctoPrint and a video streamer called ustreamer. The stated benefit is that you need no lots of file editing and no complicated Docker Compose scripts.

That last clause is the positioning. The alternative to a script like this is a compose file per instance, with its own volume layout, its own port mapping, its own reverse proxy stanza and its own camera service, and that does not scale to eight printers without becoming a maintenance job of its own.

The repository layout shows the structure of the solution. There is octoprint_deploy.sh, which is the entry point and the menu you interact with. There is instance.sh, prepare.sh and util.sh as the other shell modules. There is cameras.sh for the camera side and plugins.sh with a plugins_list file for the recommended plugins.

Then the configuration and service templates. There is config.basic, plus haproxy1x.basic and haproxy2x.basic, which are the proxy configurations for the single-instance and multi-instance cases. The systemd units are octoprint_generic.service for the print server itself, and three camera units: octocam_ustream.service, octocam_mjpg.service and octocam_camstream.service, with picam_camstream.service for the Raspberry Pi camera variant.

So the script does not just copy OctoPrint into place. It installs a running service per instance, configures cameras as services, and writes haproxy entries so each instance is reachable at a path on the host name.

The project is MIT licensed, Shell, with the last push on 2026-10-14. The release history is 1.0.15 from 2025-11-01, 1.0.3 from 2023 and 1.0.0 from 2023, while the README header still carries the version 1.0.11.

There is also a background video from the author's ERRF2022 talk that explains how it generally works, which is a faster way to understand the design than reading the script.

The install is a clone, a sudo and a menu

The usage section gives the sequence explicitly, and it is the same shape on both supported starting points.

git clone https://github.com/paukstelis/octoprint_deploy
sudo octoprint_deploy/octoprint_deploy.sh

Then you choose Prepare System from the menu and follow the prompts.

On a general Linux system, which the documentation lists as Ubuntu, Mint, RPiOS, Debian, DietPi, Armbian, Fedora, ArchLinux or openSUSE, you do not need to install OctoPrint by any other route, no wiki instructions and no snap. The script does it all. The distribution selector in the menu installs the packages, installs OctoPrint, and prompts you to create the first instance.

The prompts are where the decisions happen. You are asked whether you want to use haproxy, which makes your instances available on port 80 at a URL of the form http://hostname.local/instancename/. You are asked which streamer you would like to install, with ustreamer, mjpg-streamer and camera-streamer as the options, and the documentation notes that not all distributions will be compatible with camera-streamer, with camera-streamer support to be added at a later date.

Then the udev step, which is the part with a physical requirement. You are asked to plug in a printer via USB for udev rule creation, with the note that if you cannot plug in the printer and are only creating a single instance you can simply allow the detection to time out, and the first instance will still be created, with a rule you can generate later through the utility menu. Additional instances will require the printers to be plugged in, and so will USB cameras.

Two optional prompts follow. You are asked whether you want to set up the admin user and do the first run wizard from the command line, and you are asked whether you want to install recommended plugins.

After that you keep choosing Add Instance and following the instructions for each printer, and you can come back later. To add more printers at a later date, or to add cameras to an instance later, you simply run the script again and choose the appropriate option.

That last point is the design that makes the tool work. The script is not a one-shot installer, it is a menu you can re-enter, which is the difference between a deployment and a configuration tool.

Templates, udev and the printer identity problem

There is one change in this version that affects everyone upgrading, and it is described in the notes at the top of the documentation.

The biggest change is that there is no longer the notion of a single template OctoPrint instance. Now, any previously configured instance can be used as a template when a new instance is created, and the choice is up to the user.

The reason the previous design had a single template is that it was OctoPi's model, where one instance is configured and the others are copies of it. Letting any instance be a template is more flexible, and for a shop with two differently configured printers it is the difference between copying the right configuration and copying the wrong one.

The upgrade path is spelled out with a warning. octoprint_deploy above 1.0.0 is not directly compatible with older versions, as so much has changed. If you want to use the new version with an older setup, you create backups, either through the OctoPrint UI or with octoprint_deploy, then use the remove command line argument before updating octoprint_deploy. You then re-make your instances using the same instance names and recover your backups.

The instruction about instance names is the part to follow precisely. The remove and re-create cycle depends on the names matching, since the haproxy entries and the instance directories are keyed by them.

The printer identity problem is the other thing the script handles for you. When adding an instance you are asked if you want to use an existing instance as a template, which copies configuration files from that instance to the new one. And if your printer does not have a serial number, which is the case for all Creality printers, the script will detect and use the physical USB address for the udev entries.

That is a genuinely useful piece of automation. A udev rule that matches a serial number is stable, and a rule that matches a USB port is not, so for the printers that lack serial numbers the script falls back to the least stable option and does it for you, rather than leaving you to write the rule by hand and get it wrong.

The haproxy entries are updated as you go, so you connect via http://octopi.local/instancename.

The utility menu and the command line arguments

The utility menu is where the day-to-day work happens, and the list is a good map of the operational surface.

You can add or remove instances or cameras. You can check the status of all instances. You can do printer USB port testing. You can sync OctoPrint users from one instance to all other instances, which is the fix for the common problem of a shared farm where someone logs into one instance and not the others. You can share the uploads directory between all instances, so all instances have access to the same gcode files, which is the fix for the other common problem of uploading a print from the wrong instance. You can modify which camera streaming software is used, marked as work in progress, and modify a setting for all instances using the OctoPrint CLI interface, also marked work in progress. And you can add or remove udev rules for printers and cameras.

There is one utility item that is worth singling out. You can generate diagnostic output about octoprint_deploy, and the instruction is to use this and provide the output when you are looking for support.

Then there are the things you can do from the command line rather than the menu, and the list is short.

sudo octoprint_deploy/octoprint_deploy.sh remove

is the one to get rid of everything.

sudo octoprint_deploy/octoprint_deploy backup

backs up all instances, while backing up and restoring files for a single instance is done from the menu.

sudo octoprint_deploy/octoprint_deploy.sh restart_all

restarts all instances from the command line.

The scripts directory also has cameras.sh for the camera setup and plugins.sh with the plugins_list, which is the file listing the recommended plugins the installer can offer.

For the OctoPi path, which the documentation treats as a supported but different starting point, the sequence is shorter: ssh into the Pi, clone the repository, run the script with sudo, and choose Prepare System, which registers the OctoPi-created instance in octoprint_deploy rather than installing OctoPrint from scratch. The warning attached to OctoPi is that it is intended as a single printer environment, and while this script makes adding multiple instances easy it cannot take into account everything OctoPi does, mostly surrounding cameras.

The system requirements are honest about what will not work

The list of things that do not work is more informative than the feature list, and it is stated without hedging.

octoprint_deploy uses systemd services, so you should avoid distros that do not use systemd by default, and the examples named are MX Linux and chroot based systems like Chrome and crouton. LXC containers do not work well with udev rules and USB peripherals, so those should be avoided too.

Both exclusions have the same root cause. The script works by creating systemd services for each OctoPrint instance and by writing udev rules that give each printer a stable name. A chroot has no systemd and no device nodes, so neither mechanism functions. An LXC container has its own udev rules and its own device handling, so a printer that works on the host does not appear inside the container.

The supported list is explicit: Ubuntu 20 or later, Mint 20.3 or later, Debian, DietPi, RPiOS, Armbian, Fedora 35 or later, ArchLinux, or openSUSE, with the reminder that your user needs to be an admin for sudo. All commands assume you are operating out of your home directory.

Git is a prerequisite too, with the per-distribution install commands given: sudo apt install git, or the dnf, pacman and zypper equivalents.

The last constraint is worth stating plainly. This is a script that installs packages, creates systemd services and writes udev rules on your machine, and it wants to be run as root. The documentation says to change the default OctoPi password, since the Pi ships with known credentials, and that is the point at which the tool is asking you to take ownership of a machine it is about to reconfigure.

There is a support channel too. For help with octoprint_deploy, the documentation points at a channel on the OctoPrint Discord, and the project asks for donations through a Buy Me a Coffee page to support the work.

Editorial conclusion

Adopt octoprint_deploy if you run several printers from one Linux machine and want the whole stack, OctoPrint, cameras, proxying and services, set up without writing your own compose files. Skip it if you are on a distribution without systemd by default or in an LXC container, because the documentation says to avoid both. Verify first that your printers have udev-visible identities or that you can plug them in during setup, that you are comfortable with a script that installs packages and creates systemd services on your machine, and how you will handle the upgrade from octoprint_deploy 1.0.0, since the change is not backwards compatible and the remove command has to run first.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. paukstelis/octoprint_deploy on GitHub
4. README
5. Releases