Production Deployment

Overview

Deploying YOLO-Pi in a production environment requires careful consideration of reliability, monitoring, security, and performance. This guide covers essential practices for running YOLO-Pi at scale.

Architecture Considerations

System Components

A production YOLO-Pi deployment typically consists of:

YOLO-Pi Container(s): Running object detection on camera feeds
MQTT Broker: Message broker for publishing detection events
Backend Services: Consuming and processing detection data
Monitoring Stack: Tracking performance and health

YOLO-Pi publishes detection results to an MQTT topic called yolo with JSON payloads containing detected objects and confidence scores.

MQTT Broker Setup

YOLO-Pi requires an MQTT broker to publish detection results. The application connects to the broker specified in the MQTT environment variable.

Installing Mosquitto

Install Mosquitto

On Ubuntu/Debian:

sudo apt-get update
sudo apt-get install mosquitto mosquitto-clients

On Raspberry Pi:

sudo apt-get install mosquitto mosquitto-clients

Configure Mosquitto

Edit /etc/mosquitto/mosquitto.conf:

# Listen on all interfaces
listener 1883 0.0.0.0

# Enable persistence
persistence true
persistence_location /var/lib/mosquitto/

# Logging
log_dest file /var/log/mosquitto/mosquitto.log
log_type all

# Allow anonymous (change for production)
allow_anonymous true

For production, disable anonymous access and configure authentication (see Security section below).

Start and enable Mosquitto

sudo systemctl start mosquitto
sudo systemctl enable mosquitto

Test the broker

Subscribe to the yolo topic:

mosquitto_sub -h localhost -t yolo

When YOLO-Pi detects objects, you’ll see JSON messages like:

[{"item": "person", "score": "0.87"}, {"item": "chair", "score": "0.65"}]

Container Orchestration

Using Docker with Systemd

For single-node deployments, use systemd to manage the YOLO-Pi container:

Create systemd service file

Create /etc/systemd/system/yolo-pi.service:

[Unit]
Description=YOLO-Pi Object Detection Container
Requires=docker.service
After=docker.service mosquitto.service

[Service]
Restart=always
RestartSec=10
ExecStartPre=-/usr/bin/docker rm -f yolo-pi
ExecStart=/usr/bin/docker run --rm \
  --name yolo-pi \
  --device=/dev/video0:/dev/video0 \
  -e MQTT=192.168.1.100 \
  ashya/yolo-pi
ExecStop=/usr/bin/docker stop yolo-pi

[Install]
WantedBy=multi-user.target

Service file breakdown

Requires=docker.service: Ensures Docker is running
After=mosquitto.service: Starts after MQTT broker
Restart=always: Auto-restart on failure
RestartSec=10: Wait 10 seconds between restarts
ExecStartPre: Remove old container if exists
--rm: Clean up container on stop

Enable and start the service

sudo systemctl daemon-reload
sudo systemctl enable yolo-pi
sudo systemctl start yolo-pi

Check service status

sudo systemctl status yolo-pi
sudo journalctl -u yolo-pi -f

Using Docker Compose

For multi-container setups, use Docker Compose:

docker-compose.yml

version: '3.8'

services:
  mosquitto:
    image: eclipse-mosquitto:2
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      - ./mosquitto.conf:/mosquitto/config/mosquitto.conf
      - mosquitto-data:/mosquitto/data
      - mosquitto-logs:/mosquitto/log
    restart: unless-stopped

  yolo-pi:
    image: ashya/yolo-pi
    devices:
      - /dev/video0:/dev/video0
    environment:
      - MQTT=mosquitto
    depends_on:
      - mosquitto
    restart: unless-stopped

volumes:
  mosquitto-data:
  mosquitto-logs:

Deploy with:

docker-compose up -d

Monitoring and Logging

Container Logs

View real-time logs:

docker logs -f yolo-pi

YOLO-Pi logs include:

MQTT connection status
Model loading confirmation
Detection results with timestamps
Error messages

Log Rotation

Configure Docker log rotation in /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Restart Docker:

sudo systemctl restart docker

Health Monitoring

Monitor MQTT messages to detect issues:

# Subscribe to all topics to see activity
mosquitto_sub -h localhost -t '#' -v

If no messages appear for extended periods, the container may have crashed or the camera may be disconnected.

Resource Monitoring

Monitor container resource usage:

docker stats yolo-pi

On Raspberry Pi 3, expect:

CPU: 80-100% (during processing)
Memory: 400-600MB
Processing rate: ~0.5 FPS (1 frame per 2 seconds)

Performance Optimization

Model Selection

YOLO-Pi supports different YOLO models. Choose based on your requirements:

Model	Speed	Accuracy	Use Case
tiny-yolo-voc	Fast (~0.5 FPS on RPi3)	Lower	Production on Raspberry Pi
yolo-voc	Slow	Medium	Testing on x86
yolo-coco	Very slow	High	Development only

Configure in /app/yolo-pi.py:

model_path = 'model_data/tiny-yolo-voc.h5'
anchors_path = 'model_data/tiny-yolo-voc_anchors.txt'
classes_path = 'model_data/pascal_classes.txt'

Detection Threshold

Adjust score and IOU thresholds in yolo-pi.py:154-158:

boxes, scores, classes = yolo_eval(
    yolo_outputs,
    input_image_shape,
    score_threshold=.3,    # Increase to reduce false positives
    iou_threshold=.5)      # Adjust overlap threshold

Threshold tuning

score_threshold: Minimum confidence (0.0-1.0). Higher = fewer false positives, more missed detections
iou_threshold: Intersection over Union for non-max suppression. Higher = more overlapping boxes allowed

For production, try score_threshold=0.5 to reduce noise.

Hardware Optimization

Raspberry Pi:

Use active cooling (fan or heatsink)
Quality power supply (2.5A minimum)
Overclock (if stable): Edit /boot/config.txt
Use Camera Module instead of USB (lower latency)

x86 Systems:

Enable GPU acceleration (requires CUDA-enabled TensorFlow)
Use AVX2-optimized builds
Increase worker threads

Security Considerations

MQTT Authentication

Disable anonymous access and require authentication:

Create password file

sudo mosquitto_passwd -c /etc/mosquitto/passwd yolo-client
# Enter password when prompted

Configure Mosquitto

Edit /etc/mosquitto/mosquitto.conf:

allow_anonymous false
password_file /etc/mosquitto/passwd

Update YOLO-Pi configuration

Modify yolo-pi.py to include credentials:

client = mqtt.Client("yolo-pi")
client.username_pw_set("yolo-client", "your-password")
client.connect(mqtt_server, 1883)

Rebuild the Docker image after making changes.

Network Security

MQTT uses unencrypted communication by default. For production deployments with sensitive data, use TLS/SSL encryption.

Best practices:

Run MQTT broker on internal network only
Use firewall rules to restrict access
Enable TLS for MQTT (port 8883)
Use VPN for remote access
Never expose MQTT broker directly to the internet

Container Security

# Run with reduced privileges where possible
docker run -d \
  --device=/dev/video0:/dev/video0 \
  --cap-drop=ALL \
  --cap-add=SYS_ADMIN \
  --security-opt=no-new-privileges:true \
  --read-only \
  --tmpfs /tmp \
  -e MQTT=192.168.1.100 \
  ashya/yolo-pi

Some capabilities may be required for camera access. Test thoroughly when implementing security restrictions.

Backup and Recovery

Backup Configuration

Backup critical files:

# System configuration
tar -czf yolo-pi-config-$(date +%F).tar.gz \
  /etc/systemd/system/yolo-pi.service \
  /etc/mosquitto/mosquitto.conf \
  /etc/mosquitto/passwd

# Docker image
docker save ashya/yolo-pi | gzip > yolo-pi-image-$(date +%F).tar.gz

Disaster Recovery

Restore from backup:

# Restore image
docker load < yolo-pi-image-2026-03-04.tar.gz

# Restore configuration
tar -xzf yolo-pi-config-2026-03-04.tar.gz -C /

# Reload systemd
sudo systemctl daemon-reload
sudo systemctl start yolo-pi

Scaling Considerations

Multiple Cameras

Run multiple containers for multiple cameras:

# Camera 1
docker run -d --name yolo-pi-1 \
  --device=/dev/video0:/dev/video0 \
  -e MQTT=192.168.1.100 \
  ashya/yolo-pi

# Camera 2
docker run -d --name yolo-pi-2 \
  --device=/dev/video1:/dev/video0 \
  -e MQTT=192.168.1.100 \
  ashya/yolo-pi

Each container maps its respective camera to /dev/video0 internally. Modify the MQTT client ID in yolo-pi.py to distinguish between cameras.

Distributed Deployment

For multiple Raspberry Pi devices:

Centralize MQTT broker on a server
Configure each Pi with the broker’s IP
Use unique client IDs (modify yolo-pi.py:23)
Subscribe to yolo/# with wildcards to capture all devices

Troubleshooting Production Issues

Container keeps restarting

Check logs for errors:

docker logs yolo-pi
journalctl -u yolo-pi -n 50

Common causes:

MQTT broker unreachable
Camera device not available
Out of memory (check with docker stats)

No MQTT messages received

Verify:

Container is running: docker ps
MQTT broker is accessible: mosquitto_sub -h <broker-ip> -t yolo
Camera is working: Check container logs
No firewall blocking port 1883

High CPU usage

This is normal for YOLO-Pi. To reduce:

Lower camera resolution
Reduce frame rate (modify yolo-pi.py)
Use a more powerful device
Consider hardware acceleration

Detection accuracy is poor

Improve accuracy:

Ensure adequate lighting
Clean camera lens
Increase score_threshold to 0.5+
Use full YOLO model instead of tiny-yolo (on x86)
Train custom model on your specific use case

Getting Started

Setup

Guides

Deployment

Production Deployment

Overview

Architecture Considerations

System Components

MQTT Broker Setup

Installing Mosquitto

Container Orchestration

Using Docker with Systemd

Using Docker Compose

Monitoring and Logging

Container Logs

Log Rotation

Health Monitoring

Resource Monitoring

Performance Optimization

Model Selection

Detection Threshold

Hardware Optimization

Security Considerations

MQTT Authentication

Network Security

Container Security

Backup and Recovery

Backup Configuration

Disaster Recovery

Scaling Considerations

Multiple Cameras

Distributed Deployment

Troubleshooting Production Issues

Next Steps

Running Inference

API Reference

Build docs developers (and LLMs) love

Getting Started

Setup

Guides

Deployment

​Overview

​Architecture Considerations

​System Components

​MQTT Broker Setup

​Installing Mosquitto

​Container Orchestration

​Using Docker with Systemd

​Using Docker Compose

​Monitoring and Logging

​Container Logs

​Log Rotation

​Health Monitoring

​Resource Monitoring

​Performance Optimization

​Model Selection

​Detection Threshold

​Hardware Optimization

​Security Considerations

​MQTT Authentication

​Network Security

​Container Security

​Backup and Recovery

​Backup Configuration

​Disaster Recovery

​Scaling Considerations

​Multiple Cameras

​Distributed Deployment

​Troubleshooting Production Issues

​Next Steps

Running Inference

API Reference

Build docs developers (and LLMs) love

Overview

Architecture Considerations

System Components

MQTT Broker Setup

Installing Mosquitto

Container Orchestration

Using Docker with Systemd

Using Docker Compose

Monitoring and Logging

Container Logs

Log Rotation

Health Monitoring

Resource Monitoring

Performance Optimization

Model Selection

Detection Threshold

Hardware Optimization

Security Considerations

MQTT Authentication

Network Security

Container Security

Backup and Recovery

Backup Configuration

Disaster Recovery

Scaling Considerations

Multiple Cameras

Distributed Deployment

Troubleshooting Production Issues

Next Steps