podman-quadlet-cookbook/cookbooks/frigate

Podman Quadlet: Frigate

Overview

Frigate is a network video recorder with object detection for IP cameras. This cookbook runs it as a Podman Quadlet.

This cookbook:

• Runs the upstream image ghcr.io/blakeblackshear/frigate, pinned to a full version (0.18.2). The manifest is multi-architecture (amd64 + arm64).
• Runs Frigate as root inside its container, as the image requires (s6-overlay).
• Stores the configuration, the database and the recordings as precious data on the virtiofs mount /var/lib/virtiofs/data/frigate, so that they inherit the hypervisor's ZFS snapshots, quota and backups.
• Seeds the configuration file on first boot, then never touches it again: Frigate owns it, and its web interface writes the cameras, the masks and the zones back to it.
• Binds the unauthenticated listeners of Frigate and go2rtc to the loopback.
• Detects objects with OpenVINO on the CPU, the default of a new Frigate 0.18 configuration.
• Uses host networking.

It does not provide MQTT, a reverse proxy, nor any camera definition.

Prerequisites

• The base cookbook (implicit dependency), for the virtiofs mount.
• A virtiofs mount on /var/lib/virtiofs/data, sized for the recordings.
• Network access at the first boot, to pull the image (about 2 GB on arm64).
• CPU and memory in proportion to the cameras. Frigate's own figures are for hardware detectors; on a CPU, measure the inference time it reports under System metrics.

Files

Path	Content
/etc/quadlets/frigate/config.yml	Seed of the configuration file. Shipped by the cookbook; an operator may replace it before the first boot.
/etc/quadlets/frigate/init.sh	Copies the seed when Frigate has no configuration file yet.
/var/lib/virtiofs/data/frigate/config/	Mounted on /config: config.yml, the SQLite database, the model cache, the backup of the configuration made before each migration.
/var/lib/virtiofs/data/frigate/media/	Mounted on /media/frigate: recordings, clips, snapshots, exports.

frigate.service only starts once /var/lib/virtiofs/data/frigate/config/config.yml exists. On a fresh system, frigate-init.service creates it from the seed. Once it exists, the seed is never read again: changing /etc/quadlets/frigate/config.yml has no effect on a running installation.

The seed

The seed is the default configuration of Frigate 0.18, plus three restrictions:

• networking.listen.internal: 127.0.0.1:5000. Port 5000 serves the UI and the API without authentication. The health check and nginx reach it over the loopback; nothing else needs it.
• go2rtc.api.listen: 127.0.0.1:1984. The go2rtc API is not authenticated, and it accepts new stream sources, exec: included. It listens on every address by default.
• go2rtc.rtsp.listen: 127.0.0.1:8554. The RTSP restream is not authenticated either.

MQTT is disabled. cameras is empty: cameras are added from the web interface, or by editing config.yml on the data mount.

Ports

Port	Bound to	Use
8971/tcp	all	Web interface and API, authenticated, over TLS with a self-signed certificate
8555/tcp+udp	all	WebRTC, for live views in a browser
5000/tcp	loopback	Web interface and API, unauthenticated
1984/tcp	loopback	go2rtc API, unauthenticated
8554/tcp	loopback	RTSP restream, unauthenticated

First login

Frigate creates an admin user at its first start and prints its password in the journal:

journalctl -u frigate.service | grep -A1 -i password

Change it under Settings > Users. To print a new one, set auth.reset_admin_password: true in config.yml and restart Frigate.

Upgrades

The tag is pinned in frigate.image and frigate.container, and both must change together. A new minor version migrates config.yml in place at its first start, after copying it to backup_config.yaml. There is no migration back: going back to an older version means restoring the data mount from a snapshot taken before the upgrade.

Usage

sudo systemctl start frigate.target
sudo systemctl status frigate.service
sudo podman logs -f frigate
curl -k https://localhost:8971/

Shared memory

A camera detecting at 720p takes about 35 MB of shared memory: 1280 × 720 × 1.5 bytes for each of the 25 frames Frigate keeps. Logs and nginx cache take up to 50 MB more. ShmSize=512m thus covers eight such cameras and two added while Frigate runs. A shared memory too small shows as Bus error in the journal. The calculator in the upstream installation guide gives the size for other setups.