Skip to main content

🖨️ OctoPrint (with webcam) — Docker on Raspberry Pi

This guide shows a simple Docker Compose setup to run OctoPrint (web interface for 3D printers) together with an MJPEG webcam streamer on a Raspberry Pi. It includes device detection, a tested docker-compose example, start / stop commands and troubleshooting tips.

Prerequisites​

  • Raspberry Pi with Docker and Docker Compose installed
  • USB cable from printer to Pi (serial device like /dev/ttyUSB0 or /dev/ttyACM0)
  • USB or CSI camera (e.g. /dev/video0) or a USB webcam
  • SSH or local terminal access
  • Basic familiarity with editing files and running Docker

Detect serial and video devices​

On the Pi run:

# list serial USB devices (common names)
ls /dev/ttyUSB* /dev/ttyACM* 2>/dev/null

# list video devices
ls /dev/video* 2>/dev/null

Note the correct serial device for your printer (e.g. /dev/ttyUSB0) and the camera device (e.g. /dev/video0). Use these device paths in docker-compose.

If nothing appears, plug the device in and re-run dmesg to see kernel messages:

dmesg | tail -n 50

Create a project folder for persistence and configuration:

mkdir -p ~/docker/octoprint/reprap
cd ~/docker/octoprint
nano docker-compose.yml

Example docker-compose.yml​

This example runs OctoPrint and mjpg-streamer. Adjust device paths, ports and volumes to suit your setup.

services:
  octoprint:
    image: octoprint/octoprint:latest
    container_name: octoprint
    restart: unless-stopped
    ports:
      - "4000:5000"           # OctoPrint UI on host port 4000 -> container 5000
    devices:
      - /dev/ttyUSB0:/dev/ttyACM0   # map your printer serial device (adjust left side)
    volumes:
      - ./data:/home/octoprint      # persistent config, plugins and timelapse data
    environment:
      - TZ=Europe/Oslo              # set your timezone
    # optionally set user/group to match host if needed:
    # user: "1000:1000"

  mjpg-streamer:
    image: openhorizon/mjpg-streamer-pi3
    container_name: mjpg-streamer
    restart: unless-stopped
    devices:
      - /dev/video0:/dev/video0   # map the camera device
    ports:
      - "8080:8080"                # MJPEG stream web UI
    command: >
      ./mjpg_streamer -o "output_http.so -w ./www" -i "input_uvc.so -r 1920x1080 -d /dev/video0 -f 30"

Notes:

  • Change /dev/ttyUSB0 and /dev/video0 to the devices you found earlier.
  • The left device path is the host path; the right is the container path. Some images expect /dev/ttyACM0; mapping renames the device inside the container.
  • The mjpg-streamer resolution/rate can be adjusted to fit Pi performance (e.g. 1280x720, 15fps).

Start and manage​

Start services:

docker compose up -d

Check running containers:

docker ps

View logs (use container name or id):

docker logs -f octoprint
docker logs -f mjpg-streamer

Stop and remove:

docker compose down

Update images and restart:

docker compose pull
docker compose up -d

Access URLs​

Permissions & common issues​

  • Device not available: ensure the device exists on the host and is not claimed by another process.
  • Permission denied opening /dev/tty*: the container accesses the host device directly; run Docker commands as a user with Docker access (or use sudo). You can set udev rules or add the host user to the dialout group for persistent access.
  • Camera fails or high CPU: lower resolution and/or framerate in the mjpg-streamer command (e.g. 1280x720 -f 15). Use Raspberry Pi hardware-specific mjpg-streamer builds if available.
  • Serial autodetection in OctoPrint: go to Settings -> Serial Connection and confirm the mapped device path inside the container (e.g. /dev/ttyACM0).

Backup and data location​

  • OctoPrint data is stored in the mapped ./data directory in this example. Back up this directory to preserve settings, plugins and timelapses.
  • Example backup:
tar czf octoprint-data-backup-$(date +%F).tar.gz ./data

Security and production notes​

  • Exposing OctoPrint to the internet is risky. Use a VPN or reverse proxy with authentication and TLS if you need remote access.
  • Keep images up to date and review plugin sources before installing.
  • Limit which host devices are exposed to containers; do not map entire /dev.

Advanced tips​

  • Use Portainer to manage and monitor the containers if you already have it running.
  • If you need timelapse videos, ensure sufficient disk space and configure OctoPrint timelapse settings.
  • For better webcam performance on Raspberry Pi Camera Module (CSI), consider using software that supports the CSI interface (e.g. raspivid + ffmpeg or mjpeg tools that use libcamera).

Quick troubleshooting checklist​

  1. Confirm devices appear on host: ls /dev/tty* and ls /dev/video*
  2. Confirm containers started: docker ps
  3. Inspect logs: docker logs -f octoprint
  4. Try connecting to the serial port from host to ensure the printer is reachable (e.g. using screen or minicom)
  5. If webcam blank, test camera on host (e.g. ffmpeg or vlc) to ensure hardware works

OctoPrint and a webcam should now be running on your Raspberry Pi. Adjust paths, ports and device mappings to match your hardware. Enjoy printing!