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, and two days of continuous footage kept locally. Cloud retention is not — see CONTRIBUTING.md for the exact state and roadmap.

Install

The shortest path is one command, from a checkout:

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

It asks for the location, timezone, cameras and optional B2 credentials, validates the result through the same loader the services use, detects the host, starts the stack, and waits for Frigate. See docs/install.md for the released-image path and the by-hand alternative.

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.