Running OctoPrint in Docker on Raspberry Pi with auto‑start via udev

Use Docker and Docker Compose on Raspberry Pi to run OctoPrint in a container and automatically start it when your Creality Ender 3 Pro USB serial adapter appears.

Prerequisites on Raspberry Pi#

Make sure Raspberry Pi OS is up to date and that Docker and Docker Compose are installed.

sudo apt update
sudo apt install docker.io
sudo apt install docker-compose -y

Identify the Ender 3 Pro USB serial adapter#

Plug the printer into the Raspberry Pi via USB and list USB details.[^7]

• Run:
  • lsusb -v | grep 'idVendor\|idProduct\|iProduct\|iSerial'
• For a typical Creality Ender 3 Pro with CH340 converter you will see something like:

idVendor 0x1a86 QinHeng Electronics
idProduct 0x7523 CH340 serial converter
iProduct 2 USB Serial

This tells you the vendor and product IDs that will be used in the udev rule.

Prepare the Docker Compose file for OctoPrint#

Create a working directory and a minimal docker-compose.yml that maps the printer and a config volume into the container.

• Create directory:
  • mkdir -p ~/octoprint && cd ~/octoprint
• Create docker-compose.yml with for example:

version: "3.8"
services:
  octoprint:
    container_name: docker_octoprint_1
    image: octoprint/octoprint:latest
    restart: "no"
    ports:
      - "5000:80"
    volumes:
      - ./octoprint-config:/octoprint
    devices:
      - /dev/ttyUSB-Creality-Ender:/dev/ttyUSB0
    environment:
      - ENABLE_MJPG_STREAMER=false

• The container name docker_octoprint_1 is important because it will be used in the udev rule that starts the container.
• The device path inside the container (/dev/ttyUSB0) will point to a persistent symlink (/dev/ttyUSB-Creality-Ender) created by udev on the host.

Bring the container up once to download the image and create the config directory:

• docker-compose up -d After this first run you can stop the container again:
• docker stop docker_octoprint_1

Why Docker doesn’t start when the device is missing#

Docker cannot pass a host device into a container if the device node does not exist yet, so a container that uses devices: - /dev/ttyUSB-Creality-Ender:/dev/ttyUSB0 will fail to start automatically on boot if the printer is not plugged in. Using udev to start the container only when the USB serial device appears solves this problem cleanly.

Create the udev rule for the Ender 3 Pro#

Use the vendor and product IDs from lsusb to create a persistent device name and automatically start the OctoPrint container when the printer is connected.[^8][^10]

1. Create a udev rules file, for example:

sudo vi /etc/udev/rules.d/99-creality-ender.rules

2. Add this rule (single logical line, continued with backslash):

KERNEL=="ttyUSB*", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", \
  SYMLINK+="ttyUSB-Creality-Ender", MODE="0666", RUN+="/usr/bin/docker start docker_octoprint_1"

• ATTRS{idVendor}=="1a86" and ATTRS{idProduct}=="7523" match the CH340 USB‑serial adapter used by Creality Ender 3 Pro.
• SYMLINK+="ttyUSB-Creality-Ender" creates /dev/ttyUSB-Creality-Ender, which your Docker Compose file maps into the container.
• RUN+="/usr/bin/docker start docker_octoprint_1" starts the OctoPrint container automatically when this USB serial device appears.

3. Reload udev rules and trigger them without reboot:

sudo udevadm control --reload-rules
sudo udevadm trigger

This activates the new rule immediately.

Now, when you plug in the Ender 3 Pro, udev will create /dev/ttyUSB-Creality-Ender and start the docker_octoprint_1 container automatically.

Testing the setup#

Verify that the rule and container behavior are correct.

• Unplug the printer, then run:
  • docker stop docker_octoprint_1
• Plug the printer back in and run:
  • ls -l /dev/ttyUSB*
  • You should see ttyUSB-Creality-Ender as a symlink pointing to the underlying ttyUSBX.
• Check that the container is running:
  • docker ps | grep docker_octoprint_1
• Open OctoPrint in a browser:
  • http://<raspberry-pi-ip>:5000 and go through the initial setup wizard, selecting /dev/ttyUSB0 inside the container (which maps to the Creality symlink on the host).

With this setup OctoPrint runs in Docker on Raspberry Pi, uses a persistent device name for the Creality Ender 3 Pro USB serial adapter, and the container automatically starts whenever the printer is connected, avoiding the usual “device does not exist” problem during boot.