cctv-stack

cctv-stack is a Python toolkit and container image for a self-hosted CCTV pipeline built on Frigate.

Frigate does camera ingest, detection, recording and review segmentation. cctv-stack adds the four pieces it leaves to the operator:

1. Canonical clips — one deterministic file per review item.
2. Durable backup — clips are uploaded to Backblaze B2 exactly once.
3. Upload-aware retention — local cleanup never deletes a clip that is not safely uploaded.
4. Health surfaces — the uploader and cleanup expose /health and /metrics.

It is not a replacement for Frigate. It is the missing layer around it.

Current release: 0.7.0. Clips, B2 upload, upload-aware local retention, the aggregate status page with Gatus/ntfy alerting, a guided one-command installer, ./scripts/doctor.sh diagnosis, encrypted backups, ./update.sh upgrades, two days of continuous footage kept locally, cloud retention that only deletes an object once the provider confirms it is gone, and a daily reconciliation that reports where the bucket and the database disagree.

Built since that tag, and in master today: housekeeping that bounds the database and tidies the clip tree, footage recovery from the bucket plus reconstruction of the database when there is no backup at all (./restore.sh clips|rebuild), a real test message to every alert channel during install, and a signed release bundle. force-delete and the single-instance lock are deferred deliberately — see CONTRIBUTING.md for the exact state and roadmap.

Install

On the machine that will do the recording, with Docker Engine 24+ and the Compose v2 plugin:

git clone https://github.com/aravindmyd/cctv-stack.git
cd cctv-stack
./install.sh

It asks four things, each with a default, so the common path is pressing Enter:

Then it validates what it wrote through the same loader the services use, detects the host and sizes Frigate's shared memory, generates the two internal tokens, provisions the B2 bucket, starts the stack, waits for Frigate, and sends a real test message to every configured alert channel.

The URLs you need

Replace 192.168.1.10 with the machine's LAN address (hostname -I | awk '{print $1}').

The Frigate UI is HTTPS with a certificate Frigate generates itself, so the browser warns once. It binds to loopback on purpose: it is the one surface that can see every camera and change every setting.

Is it actually working?

Four checks, each answering a different question:

./scripts/doctor.sh                                  # 1. the machine's own verdict, read-only
curl -s http://192.168.1.10:8084/status | jq .cameras # 2. every camera delivering frames
ls -lt data/media/recordings | head                  # 3. footage landing on disk
find data/clips -name '*.mp4' -newermt '-10 minutes'  # 4. a clip exists — the entire point

docs/install.md is the full guide — prerequisites, every question the installer asks, why each URL is reachable from where it is, step-by-step verification, phone alerts, adding a camera later, upgrading, and a troubleshooting table. There is also a by-hand Compose path and a pip path for running the services against a Frigate you already have.

The Python package is usable on its own for the parts that read Frigate's API:

pip install cctv-stack

Requires Python 3.12+. The distribution is cctv-stack; the import package is cctv.

Optional extras:

pip install "cctv-stack[mqtt,storage]"

Container image

docker pull ghcr.io/aravindmyd/cctv-stack:0.7.0

Tags published per release: :0.7.0, :0.7, and the commit tag :sha-<short>. A moving :edge tag follows master. If the registry package is private, run docker login ghcr.io first. The image includes ffmpeg/ffprobe.

Commands

The four services are long-running and configuration-driven; they take no command-line arguments. Run them under systemd, Docker, or Compose.

With Compose, the answer to is my CCTV working? is at http://<host>:8084/status; the dashboard and history are at http://<host>:3001 (Gatus), and alerts arrive through ntfy at http://<host>:8085.

Quick start

The only required input is a cameras.yml. This minimal file is valid; ${VAR} values are read from the environment and an unset variable is a hard error.

site:
  location: home
  timezone: UTC

cameras:
  front-door:
    display_name: Front Door
    rtsp:
      main: ${CAMERA_FRONT_DOOR_RTSP}
      sub: ${CAMERA_FRONT_DOOR_SUB}

Validate it and generate Frigate's config:

export CAMERA_FRONT_DOOR_RTSP='rtsp://user:pass@192.168.1.10:554/stream1'
export CAMERA_FRONT_DOOR_SUB='rtsp://user:pass@192.168.1.10:554/stream2'

cctv-config validate --cameras cameras.yml
cctv-config generate --cameras cameras.yml --out frigate.yml

validate checks the camera model and the environment substitution. generate writes a Frigate config with a GENERATED FILE — DO NOT EDIT header.

Running the services

export CCTV_CONFIG_DIR="$PWD"
export CCTV_DATA_DIR="$PWD/data"
export CCTV_FRIGATE_URL="http://127.0.0.1:5000"

cctv-clip-worker

Run each service in its own process. cctv-clip-worker works without MQTT (sweep-only); set CCTV_MQTT_HOST to receive reviews immediately. cctv-uploader reports DISABLED and uploads nothing when CCTV_STORAGE_BUCKET is empty; a bucket with no key exits 78.

ffprobe must be on PATH for the clip worker. The container image includes it; a pip install does not install ffmpeg.

Configuration

There are two kinds of configuration, and they must not be mixed:

The full template is .env.example. The settings most consumers need:

Keep .env out of version control. RTSP URLs and B2 keys are credentials.

Camera names must be lowercase kebab-case (front-door): they become directory names and cloud object keys.

What it produces

$CCTV_DATA_DIR/
├── clips/
│   └── <camera>/YYYY/MM/DD/HH-MM-SS.mp4
│       <camera>/YYYY/MM/DD/HH-MM-SS.mp4.json
└── cctv.db

The clips tree is rendered in the site timezone. The sidecar records the review id, event ids, requested boundaries, measured coverage, codecs, size and SHA-256. The cloud object key is <location>/clips/<path-inside-clips>.

A clip appears after the visit ends: Frigate keeps the review open until its alert cutoff passes. There is no partial clip by design.

Health endpoints

Bind these to loopback. Nothing in the package needs an inbound port from the LAN.

Python API

The supported contract is the CLI, the environment variables, and the HTTP health endpoints. The importable modules are tested, but pre-1.0 names may change between minor versions.

from cctv.config import ConfigError, load_cameras_config

try:
    config = load_cameras_config("cameras.yml")
except ConfigError as exc:
    raise SystemExit(f"invalid camera config: {exc}")

print(config.site.location)
for name, camera in config.enabled_cameras().items():
    print(name, camera.display_name, camera.record.mode)

Storage is available behind the storage extra:

import os
from cctv.storage import S3StorageAdapter

adapter = S3StorageAdapter(
    bucket=os.environ["CCTV_STORAGE_BUCKET"],
    access_key_id=os.environ["CCTV_STORAGE_KEY_ID"],
    secret_access_key=os.environ["CCTV_STORAGE_APPLICATION_KEY"],
    region=os.environ.get("CCTV_STORAGE_REGION", "us-west-004"),
)

cctv.__version__ reports the installed package version.

Complete installation

For a full CCTV site — Frigate, MQTT, the worker, uploader and cleanup — use the Compose deployment in this repository:

git clone https://github.com/aravindmyd/cctv-stack.git
cd cctv-stack
./install.sh

The first run creates .env and config/cameras.yml; edit both and run it again. See docs/install.md for the operator procedure and CONTRIBUTING.md for how releases are built and delivered.

Compatibility

Documentation

Full documentation: https://aravindmyd.github.io/cctv-stack/

• Install — Docker Compose from the published image, or pip
• Configure — cameras.yml, .env, adding a camera
• Frigate UI login
• Health — endpoints and what to check first
• Recover failed uploads
• Glossary — the vocabulary these docs use
• CONTRIBUTING.md — development, CI and release process

License

Apache-2.0 — see LICENSE.