Deploying Viseron

Introduction

Viseron is an open-source, self-hosted Network Video Recorder (NVR) that brings AI-powered object detection to your security camera setup. Built with Python and featuring multiple detection backends, Viseron can identify people, vehicles, animals, and other objects in your camera feeds, triggering alerts and recordings only when relevant motion is detected.

Key highlights of Viseron:

• AI Object Detection: Support for multiple detection backends including YOLO, TensorFlow, and EdgeTPU
• Multi-Camera Support: Monitor multiple RTSP/RTMP camera streams simultaneously
• Smart Recording: Record only when objects of interest are detected
• Motion Detection: Configurable motion detection zones and sensitivity
• Face Recognition: Optional face recognition for person identification
• License Plate Recognition: Read and log vehicle license plates
• Home Assistant Integration: Native integration with Home Assistant
• Web Interface: Modern dashboard for viewing cameras and recordings
• Notification Support: Send alerts via MQTT, webhooks, or other services

This guide walks through deploying Viseron on Klutch.sh using Docker, configuring camera feeds, and setting up object detection.

Why Deploy Viseron on Klutch.sh

Deploying Viseron on Klutch.sh provides several advantages for video surveillance:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Viseron without complex orchestration. Push to GitHub, and your NVR deploys automatically.

Persistent Storage: Attach persistent volumes for recordings and configuration. Your security footage survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure remote access to your camera feeds.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on camera count and detection requirements.

Prerequisites

Before deploying Viseron on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with Docker and containerization concepts
• IP cameras with RTSP/RTMP stream support
• Camera stream URLs and credentials

Preparing Your Repository

Create a GitHub repository containing your Dockerfile and Viseron configuration.

Repository Structure

viseron-deploy/
├── Dockerfile
├── config.yaml
└── .dockerignore

Creating the Dockerfile

FROM roflcoopter/viseron:latest

# Copy custom configuration
COPY config.yaml /config/config.yaml

# Create directories for recordings and snapshots
RUN mkdir -p /recordings /snapshots

# Expose web interface port
EXPOSE 8888

# Volumes for persistent data
VOLUME ["/config", "/recordings", "/snapshots"]

# Health check
HEALTHCHECK --interval=60s --timeout=10s --start-period=120s --retries=3 \
  CMD curl -f http://localhost:8888/api/v1/health || exit 1

Creating the Configuration File

Create a config.yaml file:

# Viseron Configuration

# Logging configuration
logger:
  default_level: info

# Camera configuration
cameras:
  front_door:
    name: Front Door
    host: 192.168.1.100
    port: 554
    path: /stream1
    username: ${CAMERA_USERNAME}
    password: ${CAMERA_PASSWORD}
    width: 1920
    height: 1080
    fps: 15

    # Motion detection
    motion_detection:
      enabled: true
      area: 0.08
      threshold: 15

    # Object detection
    object_detection:
      enabled: true
      labels:
        - label: person
          confidence: 0.7
          trigger_recorder: true
        - label: car
          confidence: 0.7
          trigger_recorder: true
        - label: dog
          confidence: 0.6
          trigger_recorder: true

    # Recorder configuration
    recorder:
      lookback: 10
      timeout: 30
      retain:
        days: 7

# Object detection backend
object_detection:
  type: darknet
  model_path: /detectors/models/darknet/yolov4-tiny.weights
  model_config: /detectors/models/darknet/yolov4-tiny.cfg
  label_path: /detectors/models/darknet/coco.names

# Web interface
webserver:
  port: 8888
  debug: false

Environment Variables Reference

Variable	Required	Default	Description
CAMERA_USERNAME	Yes	-	Camera authentication username
CAMERA_PASSWORD	Yes	-	Camera authentication password

Deploying Viseron on Klutch.sh

Push Your Repository to GitHub

Initialize your repository and push to GitHub with your Dockerfile and configuration files.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “viseron-nvr” or “security-cameras”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Viseron Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8888

Set Environment Variables

Add the following environment variables:

Variable	Value
CAMERA_USERNAME	Your camera username
CAMERA_PASSWORD	Your camera password

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/config	1 GB	Configuration files
/recordings	100+ GB	Video recordings (adjust based on retention)
/snapshots	10 GB	Detection snapshots

Allocate Resources

Viseron benefits from adequate resources for AI detection:

• CPU: 4+ cores recommended for multiple cameras
• Memory: 4GB+ RAM for detection models

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and provision an HTTPS certificate.

Access Viseron

Once deployment completes, access your Viseron dashboard at https://your-app-name.klutch.sh.

Adding Cameras

RTSP Camera Configuration

cameras:
  backyard:
    name: Backyard Camera
    host: 192.168.1.101
    port: 554
    path: /Streaming/Channels/101
    username: ${CAMERA_USERNAME}
    password: ${CAMERA_PASSWORD}
    stream_format: rtsp

USB Camera Configuration

cameras:
  usb_camera:
    name: USB Camera
    path: /dev/video0
    width: 1280
    height: 720
    fps: 30

Configuring Object Detection

Detection Zones

Limit detection to specific areas:

cameras:
  front_door:
    object_detection:
      zones:
        - name: driveway
          coordinates:
            - [0, 500]
            - [800, 500]
            - [800, 1080]
            - [0, 1080]
          labels:
            - label: car

Custom Labels

Track specific objects:

object_detection:
  labels:
    - person
    - car
    - truck
    - bicycle
    - motorcycle
    - dog
    - cat
    - bird

Recording Management

Retention Policies

recorder:
  retain:
    days: 14

  # Cleanup recordings older than retention period
  cleanup:
    enabled: true
    interval: 86400  # Daily cleanup

Recording Triggers

cameras:
  front_door:
    recorder:
      # Start recording 10 seconds before detection
      lookback: 10
      # Continue recording 30 seconds after last detection
      timeout: 30
      # Record on motion or object detection
      trigger_on_motion: false
      trigger_on_object: true

Notifications

MQTT Integration

mqtt:
  host: mqtt.example.com
  port: 1883
  username: ${MQTT_USERNAME}
  password: ${MQTT_PASSWORD}

cameras:
  front_door:
    mqtt:
      topics:
        - object_detected
        - motion_detected

Webhook Notifications

cameras:
  front_door:
    post_processor:
      - type: webhook
        url: https://your-webhook-endpoint.com/alert
        method: POST

Troubleshooting

Camera Not Connecting

• Verify camera IP address and port
• Test RTSP URL with VLC player
• Check network connectivity between Klutch.sh and cameras
• Verify credentials are correct

High CPU Usage

• Reduce camera resolution or FPS
• Lower detection model complexity
• Increase detection interval

Recordings Not Saving

• Verify volume mount is correct
• Check available disk space
• Review recorder configuration

Additional Resources

• Viseron GitHub Repository
• Viseron Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Viseron on Klutch.sh gives you an AI-powered NVR solution with intelligent object detection and smart recording capabilities. The combination of Viseron’s detection features and Klutch.sh’s deployment simplicity means you can quickly set up intelligent video surveillance that only alerts and records when it matters.