# 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) ```bash # 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) ```bash 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 ```bash 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`