Esiah 165b3b01e7
CD — Kai-Sa-Cam Deployment / deploy (push) Failing after 3s
style: lightbox radius, nav container margin
2026-10-31 01:19:18 +01:00

Kai-Sa-Cam

Application de surveillance vidéo avec enregistrement manuel, écoute bidirectionnelle via enceinte Bluetooth, et snapshots.

Architecture

┌──────────────────────────────────────────────────────────────┐
│ Cloudflare Access  (login, session, JWT)                     │
│        │                                                     │
│ Cloudflare Tunnel (kai-sa-cam-tunnel)                        │
│  └── kaisa.esiah.dev → kai-sa-cam:8090   (seule route)       │
└──────────────────────────────┬───────────────────────────────┘
                               ▼
                    ┌─────────────────────┐
                    │  kai-sa-cam         │
                    │  UI + API + recorder│
                    │  + talkback (WS)    │
                    │  proxy /go2rtc/*    │
                    └──────────┬──────────┘
                               │ kai-sa-cam-internal (réseau interne)
                    ┌──────────▼──────────┐
                    │  kai-sa-go2rtc      │  ← aucun accès externe
                    │  (flux webcam)      │
                    └──────────┬──────────┘
                               ▼
                    /dev/video0 + /dev/snd

            kai-sa-cam ──► PulseAudio (socket hôte) ──► enceinte BT

go2rtc n'est joignable que depuis kai-sa-cam : le flux ne peut pas être consulté sans passer par Cloudflare Access.

Composants

  • kai-sa-cam : API Node + UI React/Tailwind + recorder + talkback (WebSocket → paplay → PulseAudio) + proxy /go2rtc vers go2rtc
  • kai-sa-go2rtc : flux webcam, durci (non-privileged, devices restreints), sur le réseau interne uniquement

Fonctionnalités

  • Live view : flux MSE via go2rtc, servi en même origine (/go2rtc/stream.html)
  • Push-to-record manuel : enregistrement vidéo (jamais le micro du navigateur)
  • Snapshots manuels : capture instantanée JPEG
  • Talkback : micro navigateur → enceinte Bluetooth, reconnexion automatique
  • Stockage plat : tout dans ./media sans arborescence
  • Export ZIP : téléchargement de tous les médias + suppression auto après succès
  • Auth : Cloudflare Access uniquement, avec validation optionnelle du JWT côté serveur
  • Session expirée : détectée côté client, popup de reconnexion, requête rejouée sans recharger la page

Réseaux

  • kai-sa-cam-internal (internal) : kai-sa-cam ↔ kai-sa-go2rtc
  • kai-sa-cam-tunnel (external) : exposition de kai-sa-cam uniquement via Cloudflare Tunnel

Cloudflare Access

Application Access sur kaisa.esiah.dev (aucun chemin en Bypass) :

  • Session duration : 24 h ou plus (réglage qui détermine la fréquence des reconnexions)
  • HTTP Only activé, Same Site = Lax, CORS laissé vide (tout est en même origine)
  • Aucune route de tunnel ni application Access pour go2rtc

Validation du JWT côté serveur (optionnel)

Si CF_ACCESS_TEAM_DOMAIN et CF_ACCESS_AUD sont renseignées, le serveur refuse (401) toute requête HTTP ou WebSocket sans en-tête Cf-Access-Jwt-Assertion valide. /api/health reste accessible pour les sondes locales. Vides, la vérification est désactivée.

L'AUD tag se trouve dans Zero Trust → Access → Applications → kaisa.esiah.dev.

Installation locale (dev)

# Prérequis : Docker, Docker Compose, Node.js 20+, PulseAudio/PipeWire, BlueZ
# Enceinte BT appairée (MAC: 69:B2:C0:04:A4:80)

cp .env.example .env  # adapter si besoin
make up-dev           # démarre kai-sa-cam + kai-sa-go2rtc

Accès : http://localhost:8090, ou via le proxy Vite qui doit relayer /api (WebSocket compris), /go2rtc (WebSocket compris) et /auth vers :8090.

Installation production (serveur)

cd /srv/apps/kai-sa-cam
cp .env.example .env           # une seule fois, puis renseigner CF_ACCESS_AUD
mkdir -p media config
sudo chown 1001:1001 media     # le conteneur tourne en 1001:1001
make up-prod

Le runner GitHub Actions kai-sa-cam déploie automatiquement sur push main. Le fichier .env n'est pas versionné : il reste sur le serveur d'un déploiement à l'autre.

Variables d'environnement

Lues par docker-compose.yml depuis .env :

Variable Défaut Description
TZ Europe/Paris Fuseau horaire
USER_ID / GROUP_ID 1001 UID/GID de l'utilisateur hôte
APP_ORIGIN https://kaisa.esiah.dev Origine de l'application
LOG_LEVEL info Niveau de log
MAX_RECORDING_MINUTES 120 Durée max d'un enregistrement
DISK_MIN_FREE_GB 2 Espace disque minimum
CF_ACCESS_TEAM_DOMAIN - Domaine d'équipe Access (ex. https://esiah-dev.cloudflareaccess.com)
CF_ACCESS_AUD - AUD tag de l'application Access
PULSE_SERVER unix:/run/user/1001/pulse/native Socket PulseAudio de l'hôte
BT_MAC 69:B2:C0:04:A4:80 Adresse de l'enceinte BT (service hôte)

Fixées dans le compose (pas dans .env) : MEDIA_DIR=/media, CONFIG_DIR=/config, GO2RTC_URL, GO2RTC_RTSP_URL.

Commandes Make

make up-dev       # Démarre en dev (build + hot reload)
make down-dev     # Arrête dev
make logs-dev     # Logs dev

make up-prod      # Démarre en prod
make down-prod    # Arrête prod
make logs-prod    # Logs prod
make status       # État conteneurs
make restart      # Redémarre services

Sécurité

  • go2rtc : non-privileged, devices: [/dev/video0, /dev/snd], cap_drop: ALL, no-new-privileges, read_only, réseau interne uniquement
  • kai-sa-cam : non-root (UID 1001), cap_drop: ALL, no-new-privileges, read_only, pas de D-Bus
  • Bluetooth : géré via service hôte kai-sa-cam-bt.service (pas de D-Bus dans conteneurs)
  • Auth : Cloudflare Access + validation optionnelle du JWT dans l'application

Stockage

  • ./media (hôte) monté sur /media : bind mount, pas un volume Docker. Sur le serveur : /srv/apps/kai-sa-cam/media
  • Tout est à plat (pas de sous-dossiers)
  • Enregistrements : .mp4 (push-to-record manuel, max 120 min)
  • Snapshots : .jpg (manuels)
  • Export ZIP : supprime les fichiers uniquement si le ZIP se termine sans erreur
  • Pas de rétention automatique, suppression manuelle possible

Dépannage

Symptôme Action
Pas de vidéo make status, vérifier /dev/video0, make logs-go2rtc
Bandeau « Session expirée » Cliquer « Se reconnecter » (popup Access) ; allonger la session dans Cloudflare
Tout répond 401 CF_ACCESS_AUD / CF_ACCESS_TEAM_DOMAIN incorrects : les vider pour désactiver la vérification
Micro → enceinte ne marche pas make logs-cam, vérifier Pulse/BT
Enregistrement ne démarre pas Espace disque, droits sur ./media (1001:1001), make logs-cam

Déploiement

Le workflow GitHub Actions .github/workflows/deploy.yml tourne sur runner self-hosted label kai-sa-cam :

  1. git pull sur /srv/apps/kai-sa-cam
  2. docker compose --profile prod build
  3. docker compose --profile prod up -d
  4. docker image prune -f
S
Description
No description provided
Readme
1.7 MiB
Languages
TypeScript 88.7%
CSS 4.1%
Makefile 2.9%
Shell 1.7%
Dockerfile 1.5%
Other 1.1%