Modularize bridge and improve control GUI

2026-08-03 00:55:12 +02:00
parent 73b302a965
commit f4ab49e0c8
26 changed files with 3104 additions and 1953 deletions
@@ -0,0 +1,61 @@
+# Docker Compose Example
+
+This directory shows two Docker Compose patterns:
+
+- `compose.yaml`: Frigate and the camera-control bridge run side by side in the
+  same Compose project.
+- `compose.sidecar-only.yaml`: only the bridge is added next to an existing
+  Frigate container on an existing Docker network.
+
+In both patterns, the bridge manages exactly one Frigate instance.
+
+## Full Stack
+
+1. Build the bridge image from the repository root:
+
+```bash
+docker build -t frigate-camera-control-bridge:1.0 .
+```
+
+2. Copy the env template:
+
+```bash
+cp examples/docker-compose/camera-control.env.example examples/docker-compose/camera-control.env
+```
+
+3. Edit `examples/docker-compose/camera-control.env` and set MQTT plus camera
+   credentials.
+
+4. Start the stack:
+
+```bash
+docker compose -f examples/docker-compose/compose.yaml up -d
+```
+
+The fallback GUI will be available on:
+
+```text
+http://localhost:5011/
+```
+
+## Sidecar Next To Existing Frigate
+
+Use `compose.sidecar-only.yaml` when Frigate is already running in Docker and
+the bridge only needs to join the same network.
+
+1. Make sure the external network in the example exists and contains Frigate:
+
+```bash
+docker network ls
+```
+
+2. Edit `compose.sidecar-only.yaml`:
+
+- set `networks.frigate-network.external` to the network name used by Frigate,
+- set `FRIGATE_URL` to the Frigate container DNS name or another reachable URL.
+
+3. Start only the bridge:
+
+```bash
+docker compose -f examples/docker-compose/compose.sidecar-only.yaml up -d
+```
@@ -0,0 +1,27 @@
+MQTT_HOST=mqtt.example.test
+MQTT_PORT=1883
+MQTT_USER=change-me
+MQTT_PASSWORD=change-me
+
+DEFAULT_CAMERA_USER=admin
+DEFAULT_CAMERA_PASSWORD=change-me
+
+HTTP_PORT=5011
+UI_LANGUAGE=en
+WAIT_FOR_FRIGATE=true
+FRIGATE_RETRY_SECONDS=5
+FRIGATE_STARTUP_WAIT_SECONDS=0
+FRIGATE_REFRESH_SECONDS=300
+
+SNAPSHOT_ENABLED=true
+SNAPSHOT_HEIGHT=180
+SNAPSHOT_CACHE_SECONDS=300
+SNAPSHOT_RETRY_SECONDS=600
+SNAPSHOT_REFRESH_SECONDS=3600
+SNAPSHOT_LIVE_ON_GUI=true
+
+STARTUP_ALL_OFF=true
+AUTO_OFF_SIREN_SECONDS=180
+AUTO_OFF_RED_BLUE_SECONDS=300
+AUTO_OFF_WHITE_LIGHT_SECONDS=600
+AUTO_OFF_DEFAULT_SECONDS=0
@@ -0,0 +1,27 @@
+services:
+  # Use this variant when Frigate already exists and this bridge should be added
+  # next to it on the same Docker network.
+  camera-control:
+    image: frigate-camera-control-bridge:1.0
+    container_name: frigate-camera-control-bridge
+    restart: unless-stopped
+    env_file:
+      - camera-control.env
+    environment:
+      FRIGATE_NAME: frigate-main
+      # Set this to the Frigate container DNS name or another reachable URL.
+      FRIGATE_URL: http://frigate:5000
+      BASE_TOPIC: frigate_camera_control/frigate-main
+    ports:
+      - "5011:5011"
+    volumes:
+      - camera-control-state:/var/lib/frigate-camera-control-bridge
+    networks:
+      - frigate-network
+
+volumes:
+  camera-control-state:
+
+networks:
+  frigate-network:
+    external: true
@@ -0,0 +1,36 @@
+services:
+  # Main Frigate container. Replace volumes/devices with the configuration that
+  # your Frigate installation needs.
+  frigate:
+    image: ghcr.io/blakeblackshear/frigate:stable
+    container_name: frigate
+    restart: unless-stopped
+    ports:
+      - "5000:5000"
+    volumes:
+      - ./frigate-config:/config
+      - ./frigate-media:/media/frigate
+
+  # Sidecar for exactly this Frigate instance. It discovers cameras from the
+  # Frigate API and exposes MQTT/GUI controls for the detected camera features.
+  camera-control:
+    image: frigate-camera-control-bridge:1.0
+    container_name: frigate-camera-control-bridge
+    restart: unless-stopped
+    depends_on:
+      - frigate
+    env_file:
+      - camera-control.env
+    environment:
+      FRIGATE_NAME: frigate-main
+      # Because both containers share the same Compose network, the sidecar can
+      # reach Frigate by service name.
+      FRIGATE_URL: http://frigate:5000
+      BASE_TOPIC: frigate_camera_control/frigate-main
+    ports:
+      - "5011:5011"
+    volumes:
+      - camera-control-state:/var/lib/frigate-camera-control-bridge
+
+volumes:
+  camera-control-state:
@@ -0,0 +1,37 @@
+# Kubernetes Examples
+
+This directory contains two deployment patterns for one Frigate instance.
+
+## Same Pod
+
+`same-pod.yaml` runs Frigate and the bridge as two containers in one Pod:
+
+- `camera-control` is a real sidecar,
+- both containers share the Pod network namespace,
+- `FRIGATE_URL=http://127.0.0.1:5000`,
+- this is the lowest-latency and simplest option when the bridge lifecycle
+  should follow the Frigate Pod.
+
+```bash
+kubectl apply -f examples/kubernetes/same-pod.yaml
+```
+
+For an existing Frigate Deployment, copy only the `camera-control` container
+block into the existing Pod template and keep `FRIGATE_URL` pointed at
+`http://127.0.0.1:5000`.
+
+## Two Pods
+
+`two-pods.yaml` runs Frigate and the bridge as separate Deployments:
+
+- Frigate is exposed through a Kubernetes Service named `frigate`,
+- the bridge uses `FRIGATE_URL=http://frigate:5000`,
+- the bridge has its own lifecycle and can be restarted independently,
+- this is useful when adding the bridge next to an existing Frigate Deployment.
+
+```bash
+kubectl apply -f examples/kubernetes/two-pods.yaml
+```
+
+For production, replace image names, storage, device access, resource requests,
+and secret names with values from your cluster.
@@ -31,12 +31,22 @@ spec:
              value: frigate_camera_control/frigate-main
            - name: UI_LANGUAGE
              value: en
+            - name: FRIGATE_REFRESH_SECONDS
+              value: "300"
            - name: SNAPSHOT_RETRY_SECONDS
              value: "600"
            - name: SNAPSHOT_REFRESH_SECONDS
              value: "3600"
            - name: SNAPSHOT_LIVE_ON_GUI
              value: "true"
+            - name: STARTUP_ALL_OFF
+              value: "true"
+            - name: AUTO_OFF_SIREN_SECONDS
+              value: "180"
+            - name: AUTO_OFF_RED_BLUE_SECONDS
+              value: "300"
+            - name: AUTO_OFF_WHITE_LIGHT_SECONDS
+              value: "600"
            - name: MQTT_USER
              valueFrom:
                secretKeyRef:
@@ -0,0 +1,130 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: frigate
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: frigate
+  template:
+    metadata:
+      labels:
+        app: frigate
+    spec:
+      containers:
+        - name: frigate
+          image: ghcr.io/blakeblackshear/frigate:stable
+          ports:
+            - name: http
+              containerPort: 5000
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: frigate
+spec:
+  selector:
+    app: frigate
+  ports:
+    - name: http
+      port: 5000
+      targetPort: http
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: frigate-camera-control
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: frigate-camera-control
+  template:
+    metadata:
+      labels:
+        app: frigate-camera-control
+    spec:
+      containers:
+        - name: camera-control
+          image: registry.example.local/frigate-camera-control-bridge:1.0
+          env:
+            - name: FRIGATE_NAME
+              value: frigate-main
+            - name: FRIGATE_URL
+              value: http://frigate:5000
+            - name: MQTT_HOST
+              value: mqtt.default.svc.cluster.local
+            - name: BASE_TOPIC
+              value: frigate_camera_control/frigate-main
+            - name: UI_LANGUAGE
+              value: en
+            - name: FRIGATE_REFRESH_SECONDS
+              value: "300"
+            - name: STARTUP_ALL_OFF
+              value: "true"
+            - name: AUTO_OFF_SIREN_SECONDS
+              value: "180"
+            - name: AUTO_OFF_RED_BLUE_SECONDS
+              value: "300"
+            - name: AUTO_OFF_WHITE_LIGHT_SECONDS
+              value: "600"
+            - name: MQTT_USER
+              valueFrom:
+                secretKeyRef:
+                  name: frigate-camera-control
+                  key: mqtt-user
+            - name: MQTT_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: frigate-camera-control
+                  key: mqtt-password
+            - name: DEFAULT_CAMERA_USER
+              valueFrom:
+                secretKeyRef:
+                  name: frigate-camera-control
+                  key: camera-user
+            - name: DEFAULT_CAMERA_PASSWORD
+              valueFrom:
+                secretKeyRef:
+                  name: frigate-camera-control
+                  key: camera-password
+            - name: HTTP_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: frigate-camera-control
+                  key: http-token
+                  optional: true
+          ports:
+            - name: control-http
+              containerPort: 5011
+          readinessProbe:
+            httpGet:
+              path: /readyz
+              port: control-http
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: control-http
+            initialDelaySeconds: 20
+            periodSeconds: 30
+          volumeMounts:
+            - name: camera-control-state
+              mountPath: /var/lib/frigate-camera-control-bridge
+      volumes:
+        - name: camera-control-state
+          emptyDir: {}
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: frigate-camera-control
+spec:
+  selector:
+    app: frigate-camera-control
+  ports:
+    - name: control-http
+      port: 5011
+      targetPort: control-http
@@ -1,36 +1,5 @@
 # Podman Quadlet Example

-## PL
-
-To jest generyczny przyklad uruchomienia kontenera
-`frigate-camera-control-bridge` przez Podman Quadlet. Pliki sa przykladem dla
-jednej instancji Frigate. Dla wielu instancji skopiuj `.container` oraz `.env`
-i zmien `FRIGATE_NAME`, `FRIGATE_URL`, `BASE_TOPIC`, port publikowany przez
-`PublishPort` oraz credentiale MQTT.
-
-Przykladowa instalacja:
-
-```bash
-install -d /etc/frigate-camera-control-bridge
-install -m 0600 frigate-camera-control-bridge.env.example \
-  /etc/frigate-camera-control-bridge/frigate-main.env
-install -m 0644 frigate-camera-control-bridge.container \
-  /etc/containers/systemd/frigate-camera-control-bridge.container
-systemctl daemon-reload
-systemctl enable --now frigate-camera-control-bridge.service
-```
-
-W pliku env uzupelnij:
- `MQTT_HOST`, `MQTT_USER`, `MQTT_PASSWORD`
- `DEFAULT_CAMERA_USER`, `DEFAULT_CAMERA_PASSWORD`
- `FRIGATE_NAME`, `FRIGATE_URL`, `BASE_TOPIC`
-
-Jesli sidecar ma startowac razem z istniejaca usluga Frigate, dopasuj w
-`.container` nazwe `frigate.service` w polach `After`, `Requires`, `BindsTo`
-i `PartOf`.
-
-## EN
-
 This is a generic example for running `frigate-camera-control-bridge` with
 Podman Quadlet. The files model one Frigate instance. For multiple instances,
 copy the `.container` and `.env` files and change `FRIGATE_NAME`,
@@ -15,6 +15,7 @@ UI_LANGUAGE=en
 WAIT_FOR_FRIGATE=true
 FRIGATE_RETRY_SECONDS=5
 FRIGATE_STARTUP_WAIT_SECONDS=0
+FRIGATE_REFRESH_SECONDS=300

 SNAPSHOT_ENABLED=true
 SNAPSHOT_HEIGHT=180
@@ -22,3 +23,9 @@ SNAPSHOT_CACHE_SECONDS=300
 SNAPSHOT_RETRY_SECONDS=600
 SNAPSHOT_REFRESH_SECONDS=3600
 SNAPSHOT_LIVE_ON_GUI=true
+
+STARTUP_ALL_OFF=true
+AUTO_OFF_SIREN_SECONDS=180
+AUTO_OFF_RED_BLUE_SECONDS=300
+AUTO_OFF_WHITE_LIGHT_SECONDS=600
+AUTO_OFF_DEFAULT_SECONDS=0