Frigate NVR Setup Guide: How to Install and Configure for Beginners

Frigate NVR Setup Guide: How to Install and Configure for Beginners

1. Understanding Frigate NVR and Its Hardware Requirements
Frigate is an open-source Network Video Recorder (NVR) designed specifically for real-time object detection using AI. Unlike traditional NVR software that relies on motion detection (which triggers on leaves, shadows, or lighting changes), Frigate uses deep learning models—primarily Google Coral TPU—to identify humans, animals, vehicles, and packages. This drastically reduces false alerts and improves video analysis accuracy.

Before installation, verify your hardware meets baseline specifications. Frigate runs as a Docker container on Linux, Windows (via WSL2), or macOS. An Intel processor with Quick Sync Video (QSV) or an Nvidia GPU for hardware acceleration is highly recommended. However, the critical component is a Google Coral USB Accelerator (Edge TPU). Without it, Frigate can still function, but performance will degrade significantly (e.g., 2-3 FPS detection instead of 15-20 FPS). Additional RAM and storage depend on camera count: 4GB RAM + 20GB storage for a single 1080p camera, scaling to 8GB+ for 4-6 cameras.

2. Operating System Preparation (Ubuntu/Debian)
Install a minimal Ubuntu Server 22.04 LTS or Debian 12 on a dedicated machine or virtual machine (Proxmox, ESXi). Do not use a desktop environment; conserve resources for Frigate. Update the system:

sudo apt update && sudo apt upgrade -y

Install essential dependencies:

sudo apt install -y curl wget git docker.io docker-compose-v2

Enable Docker and add your user to the docker group (log out and back in):

sudo systemctl enable --now docker
sudo usermod -aG docker $USER

Critical: Configure hardware access. For Intel QSV, install the intel-media-va-driver and vainfo tools:

sudo apt install intel-media-va-driver-non-free libva-drm2 vainfo

For Coral TPU, you must install the Coral library on the host (not inside the container). Download and run the installer:

wget https://packages.cloud.google.com/apt/dists/coral-edgetpu-stable/Release.key
sudo apt-key add Release.key
echo "deb https://packages.cloud.google.com/apt coral-edgetpu-stable main" | sudo tee /etc/apt/sources.list.d/coral-edgetpu.list
sudo apt update
sudo apt install libedgetpu1-std

Note: Use libedgetpu1-std for standard performance (lower temps) or libedgetpu1-max for maximum speed (requires heatsink/fan).

3. Docker Compose File Construction
Create a dedicated directory: mkdir ~/frigate && cd ~/frigate. Create docker-compose.yml with the following template. Replace /path/to/config with a real path (e.g., /home/user/frigate/config) and /path/to/media for storage (e.g., /mnt/storage/frigate).

version: "3.9"
services:
  frigate:
    container_name: frigate
    privileged: true
    restart: unless-stopped
    image: ghcr.io/blakeblackshear/frigate:stable
    shm_size: "64mb"
    devices:
      - /dev/bus/usb:/dev/bus/usb  # Coral USB
      - /dev/dri:/dev/dri          # Intel GPU for hw accel
      - /dev/video10:/dev/video10  # VAAPI GPU entry (optional)
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - /path/to/config:/config
      - /path/to/media:/media/frigate
      - type: tmpfs
        target: /tmp/cache
        tmpfs:
          size: 1000000000
    ports:
      - "5000:5000"     # Web UI
      - "1935:1935"     # RTMP feeds
    environment:
      - FRIGATE_RTSP_PASSWORD=""  # Optional
    cap_add:
      - CAP_PERFMON     # For perf counters

Important: The shm_size sets shared memory for inter-process communication. 64MB is a minimum; increase to 128MB-256MB for 4+ cameras. If using an Nvidia GPU, add deploy section with resources.reservations.devices (requires nvidia-docker2).

4. Base Camera Configuration (config.yml)
Inside your /path/to/config directory, create config.yml. This minimalist configuration initializes a single camera for testing:

mqtt:
  enabled: false  # Enable later if using Home Assistant
cameras:
  front_door:
    ffmpeg:
      inputs:
        - path: rtsp://username:password@192.168.1.100:554/stream1
          roles:
            - detect
    detect:
      enabled: true
      width: 1280
      height: 720
      fps: 5
    motion:
      mask:
        - 0,0,0,1080,1920,1080,1920,0  # Example crop mask

Explanation:

• RTSP URL: Replace with your camera’s actual RTSP stream. Use stream1 (high-res) for detection, stream2 (low-res) for sub-stream if supported.
• detect.fps: 5 FPS is a good balance for object detection. Higher FPS increases CPU/TPU load.
• motion.mask: Optional polygon coordinates to ignore certain areas (e.g., treetops, roads). Use the Frigate UI’s mask editor later to generate these.

To test, run docker compose up -d in the ~/frigate directory. Access the Web UI at http://your-server-ip:5000. You should see the camera feed with detection boxes appearing over objects.

5. Optimizing Detection with the Google Coral TPU
The Coral TPU dramatically accelerates TensorFlow Lite object detection. To verify the TPU is detected, check the Frigate logs:

docker logs -f frigate | grep -i coral

If you see TPU: [system], NoEdgeTPU detected, or TPU: [PCI] (for PCIe version), debugging steps include:

• Confirm USB 3.0 port is used (blue interior).
• Check USB device ownership: ls -la /dev/bus/usb — the Coral should appear as Google Inc..
• Install udev rules: echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="18d1", ATTRS{idProduct}=="9302", MODE="0660", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/99-gcp-coral.rules

In config.yml, explicitly set the detector to Coral:

detectors:
  coral:
    type: edgetpu
    device: usb

If using multiple Coral devices, specify device paths (e.g., /dev/coral1, /dev/coral2).

6. Sub-Stream Configuration for Performance
Most modern IP cameras offer a sub-stream (e.g., 640×480 at 5fps) alongside the main stream (e.g., 3840×2160 at 15fps). Frigate can process the sub-stream for detection while recording the main stream. This reduces CPU/TPU load by up to 80%. Update your camera config:

cameras:
  front_door:
    ffmpeg:
      inputs:
        - path: rtsp://user:pass@192.168.1.100:554/stream1
          roles:
            - record
        - path: rtsp://user:pass@192.168.1.100:554/stream2
          roles:
            - detect
    detect:
      width: 640
      height: 480
      fps: 5
    record:
      enabled: true
      retain:
        days: 7

Key: The detect role uses the sub-stream; record uses the main stream. You must adjust detect.width/height to match the sub-stream resolution. Cameras like Dahua, Hikvision, and Reolink typically provide sub-streams at stream2 or Channel2.

7. Motion Masks and Zone Configuration
Unwanted motion triggers (tree branches, car headlights) waste resources. Use the Frigate UI to draw motion masks. Navigate to the camera feed, click “…” > “Edit mask”, then click and drag to create polygons. The mask is applied before detection, so objects inside a motion mask will not trigger AI inspection.

Zones enable alert filtering per area. For example, create a “Front_Walkway” zone that only triggers alerts for humans or packages in that specific geographic area. Add to config.yml:

cameras:
  front_door:
    zones:
      walkway:
        coordinates: 100,200,300,400,500,600  # Polygon in pixel coords
        objects:
          - person
          - package
    motion:
      mask:
        - 0,0,0,1080,1920,1080,1920,0

Zones are pixel-based—use the UI’s debug mode to see coordinates. For multiple zones, duplicate the block.

8. Recording and Retention Settings
Frigate records based on events (object detection) unless configured for continuous recording. For beginners, event-based recording conserves disk space. In config.yml under cameras::

record:
  enabled: true
  retain:
    mode: motion  # 'all' for 24/7, 'motion' for events only
    days: 7
  events:
    pre_capture: 5   # seconds before detection
    post_capture: 10  # seconds after detection
    required_zones: [] # leave empty for all zones
    objects:
      - person
      - car

For 24/7 recording (high storage consumption), set mode: all and adjust days accordingly. A 4K camera at 15fps consumes ~15GB/day. Use H.265 encoding to reduce by 40-50%.

9. Hardware Acceleration Encoding (VAAPI/QSV)
Without hardware acceleration, a 4K stream can consume 30-40% CPU. Enable Intel Quick Sync:

ffmpeg:
  hwaccel_args: preset-vaapi
cameras:
  front_door:
    ffmpeg:
      hwaccel: vaapi
      input_args: preset-rtsp-generic

For Nvidia GPUs (GTX 1050Ti or newer, with nvidia-docker2):

ffmpeg:
  hwaccel_args: preset-nvidia
cameras:
  front_door:
    ffmpeg:
      hwaccel: cuda
      output_args:
        record: -f segment -segment_time 60 -segment_format mp4 -reset_timestamps 1 -c:v h264_nvenc

Test: Run a stream for 10 minutes, then check host CPU usage with htop. If acceleration is working, CPU usage for that stream should drop below 5-10%.

10. Home Assistant Integration (MQTT)
For smart home users, Frigate publishes detection events over MQTT. First, set up an MQTT broker (Mosquitto) in a separate container or use the Home Assistant add-on. Edit config.yml:

mqtt:
  host: 192.168.1.50   # MQTT broker IP
  port: 1883
  user: mqtt_user
  password: secure_pw
  topic_prefix: frigate

In Home Assistant, install the “Frigate” integration via HACS or manually. It automatically discovers cameras, zones, and sensors. You can create automations like “Send push notification when a person enters the driveway zone after 10 PM.”

11. Troubleshooting Common Issues for Beginners

• Camera offline: Check RTSP URL syntax; some cameras use rtsp://user:pass@ip:port/cam/stream1. Use VLC to test the stream externally.
• No detections: Ensure objects list is not over-restricted (default includes person, car, cat, dog). Increase min_score from 0.5 to 0.7 for fewer false positives.
• High CPU usage: Disable sub-stream detection or reduce detect FPS to 3. Ensure hardware acceleration is active (docker logs frigate | grep -i hwaccel).
• Recording never starts: Verify record.enabled: true and that the camera’s main stream path is correct. Check Frigate’s events tab for “Recording not started” errors.

12. Security Considerations
Never expose the Frigate Web UI directly to the internet without authentication. Use a reverse proxy (Nginx, Traefik) with SSL and HTTP basic auth. Set strong passwords for RTSP streams—many cameras have default credentials like admin:admin. Update your camera firmware to prevent unauthenticated access. For LAN-only deployment, at minimum isolate Frigate on a VLAN separate from guest Wi-Fi.