Docker Setup

Overview

Docker provides the easiest way to run YOLO-Pi by packaging all dependencies, including OpenCV, TensorFlow, and Keras, into a single container image. YOLO-Pi includes separate Dockerfiles for x86 (laptops/desktops) and ARM (Raspberry Pi) platforms.

Architecture Support

Platform	Dockerfile	Base Image	Build Time
x86/x64	`Dockerfile.x86`	`python:3.6`	~20 minutes
ARM (RPi)	`Dockerfile.rpi`	`resin/rpi-raspbian:stretch`	Several hours

Prerequisites

Install Docker

On Linux/macOS:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

On Raspberry Pi:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

Log out and back in for group changes to take effect.

Verify Camera Device

Ensure your USB camera is detected:

ls -l /dev/video0

If not found, check connected cameras:

v4l2-ctl --list-devices

Building for x86/x64

The x86 Dockerfile is optimized for development and testing on laptops and desktops.

Review Dockerfile.x86

The x86 Dockerfile includes:

Python 3.6 base image
System dependencies (build tools, libraries)
Python packages: NumPy, Keras 2.1.2, TensorFlow 1.1.0, Pillow 4.3.0, h5py 2.7.1
OpenCV 3.3.0 compiled from source with optimizations (AVX, OpenGL, OpenCL, TBB, Eigen)
Kafka-python for messaging (alternative to MQTT)

Build Image

docker build -t ashya/yolo-pi --file Dockerfile.x86 .

This takes approximately 20 minutes on modern hardware due to OpenCV compilation.

Run Container

Run with camera access and current directory mounted:

docker run -it --rm --privileged \
  --device=/dev/video0:/dev/video0 \
  -v $(pwd):/app \
  ashya/yolopi /bin/bash

Parameters explained:

-it: Interactive terminal
--rm: Remove container after exit
--privileged: Grant extended privileges (required for camera access)
--device=/dev/video0:/dev/video0: Mount camera device
-v $(pwd):/app: Mount current directory to /app in container

Building for ARM (Raspberry Pi)

The ARM Dockerfile is specifically configured for Raspberry Pi hardware.

Prepare Build Environment

On Raspberry Pi, set up a USB swap drive before building. See the Raspberry Pi setup guide for detailed instructions.

# Quick swap setup
sudo dphys-swapfile setup
sudo dphys-swapfile swapon

Download TensorFlow Wheel

The ARM build requires a pre-compiled TensorFlow binary:

cd ~/src
wget https://github.com/samjabrahams/tensorflow-on-raspberry-pi/releases/download/v1.1.0/tensorflow-1.1.0-cp34-cp34m-linux_armv7l.whl
mv tensorflow-1.1.0-cp34-cp34m-linux_armv7l.whl tensorflow-1.1.0-cp35-cp35m-linux_armv7l.whl

Place Dockerfile.rpi in the same directory as the wheel file.

Build Image (Long Process)

Use screen to maintain your session during the long build:

screen
docker build -t ashya/yolo-pi -f Dockerfile.rpi .

Press Ctrl+A then D to detach. Reattach later with screen -r.

Building on Raspberry Pi 3 takes several hours due to compiling OpenCV from source. Be patient and ensure stable power.

Run Container

Run with camera access:

docker run -it --rm --device /dev/video0 ashya/yolo-pi /bin/bash

Or run in detached mode:

docker run -d --device /dev/video0 ashya/yolo-pi

Dockerfile Comparison

FROM python:3.6
MAINTAINER Vallard Benincosa

RUN apt-get update && \
        apt-get install -y \
        build-essential cmake git wget unzip yasm \
        pkg-config libswscale-dev libtbb2 libtbb-dev \
        libjpeg-dev libpng-dev libtiff-dev libavformat-dev \
        libpq-dev libgtk2.0-dev pkg-config

RUN pip install numpy \
        keras==2.1.2 \
        tensorflow==1.1.0 \
        pillow==4.3.0 \
        kafka-python \
        h5py==2.7.1

# Build OpenCV 3.3.0 with optimizations
WORKDIR /
RUN wget https://github.com/opencv/opencv/archive/3.3.0.zip \
&& unzip 3.3.0.zip \
&& mkdir /opencv-3.3.0/cmake_binary \
&& cd /opencv-3.3.0/cmake_binary \
&& cmake -DBUILD_TIFF=ON \
  -DBUILD_opencv_java=OFF \
  -DWITH_CUDA=OFF \
  -DENABLE_AVX=ON \
  -DWITH_OPENGL=ON \
  -DWITH_OPENCL=ON \
  -DWITH_IPP=ON \
  -DWITH_TBB=ON \
  -DWITH_EIGEN=ON \
  -DWITH_V4L=ON \
  -DBUILD_TESTS=OFF \
  -DBUILD_PERF_TESTS=OFF \
  -DCMAKE_BUILD_TYPE=RELEASE \
  -DCMAKE_INSTALL_PREFIX=$(python3.6 -c "import sys; print(sys.prefix)") \
  -DPYTHON_EXECUTABLE=$(which python3.6) \
  -DPYTHON_INCLUDE_DIR=$(python3.6 -c "from distutils.sysconfig import get_python_inc; print(get_python_inc())") \
  -DPYTHON_PACKAGES_PATH=$(python3.6 -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())") .. \
&& make install \
&& rm /3.3.0.zip \
&& rm -r /opencv-3.3.0

ADD src/ /app
WORKDIR /app
CMD ["python3", "yolo-pi.py"]

Environment Variables

The YOLO-Pi script requires the MQTT environment variable to connect to your MQTT broker.

Setting MQTT Server

# Run with environment variable
docker run -it --rm \
  --device=/dev/video0:/dev/video0 \
  -e MQTT=192.168.1.100 \
  ashya/yolopi

Or use a .env file:

.env

MQTT=192.168.1.100

docker run -it --rm \
  --device=/dev/video0:/dev/video0 \
  --env-file .env \
  ashya/yolopi

Volume Mounts

Mount local directories to customize model files or access output:

Mount Model Data

docker run -it --rm \
  --device=/dev/video0:/dev/video0 \
  -v $(pwd)/model_data:/app/model_data \
  -e MQTT=192.168.1.100 \
  ashya/yolopi

Mount Source Code for Development

docker run -it --rm \
  --device=/dev/video0:/dev/video0 \
  -v $(pwd)/src:/app \
  -e MQTT=192.168.1.100 \
  ashya/yolopi /bin/bash

This allows you to edit yolo-pi.py locally and test changes in the container.

Docker Compose

For easier management, create a docker-compose.yml:

docker-compose.yml

version: '3.8'

services:
  yolopi:
    image: ashya/yolopi
    container_name: yolo-pi
    privileged: true
    devices:
      - /dev/video0:/dev/video0
    environment:
      - MQTT=192.168.1.100
    volumes:
      - ./model_data:/app/model_data
    restart: unless-stopped

Run with:

docker-compose up -d

Troubleshooting

Permission denied: /dev/video0

Add your user to the video group:

sudo usermod -aG video $USER

Or run with --privileged flag (already included in examples).

Build fails on Raspberry Pi

Check swap space:

free -h

Ensure at least 2GB swap is active. See Raspberry Pi setup.

MQTT connection error

Verify the MQTT environment variable is set:

docker run -it --rm \
  --device=/dev/video0:/dev/video0 \
  -e MQTT=your-mqtt-server \
  ashya/yolopi /bin/bash

Test MQTT connection from within container:

echo $MQTT
ping $MQTT

Out of disk space during build

Docker builds require significant disk space. Clean up unused images:

docker system prune -a

Performance Optimization

Use Pre-built Images

Instead of building locally, pull pre-built images if available:

docker pull ashya/yolopi

Multi-stage Builds

For production, consider creating a multi-stage Dockerfile to reduce final image size by separating build and runtime dependencies.

Cache Build Layers

When rebuilding, Docker caches intermediate layers. To rebuild from scratch:

docker build --no-cache -t ashya/yolo-pi -f Dockerfile.x86 .

Getting Started

Setup

Guides

Deployment

Overview

Architecture Support

Prerequisites

Building for x86/x64

Building for ARM (Raspberry Pi)

Dockerfile Comparison

Environment Variables

Setting MQTT Server

Volume Mounts

Mount Model Data

Mount Source Code for Development

Docker Compose

Troubleshooting

Performance Optimization

Use Pre-built Images

Multi-stage Builds

Cache Build Layers

Next Steps

Raspberry Pi Setup

Model Conversion

Build docs developers (and LLMs) love

Getting Started

Setup

Guides

Deployment

​Overview

​Architecture Support

​Prerequisites

​Building for x86/x64

​Building for ARM (Raspberry Pi)

​Dockerfile Comparison

​Environment Variables

​Setting MQTT Server

​Volume Mounts

​Mount Model Data

​Mount Source Code for Development

​Docker Compose

​Troubleshooting

​Performance Optimization

Use Pre-built Images

Multi-stage Builds

Cache Build Layers

​Next Steps

Raspberry Pi Setup

Model Conversion

Build docs developers (and LLMs) love

Overview

Architecture Support

Prerequisites

Building for x86/x64

Building for ARM (Raspberry Pi)

Dockerfile Comparison

Environment Variables

Setting MQTT Server

Volume Mounts

Mount Model Data

Mount Source Code for Development

Docker Compose

Troubleshooting

Performance Optimization

Next Steps