zwitschi
926a663c23
- Created README.md in docs folder outlining project structure and documentation links. - Added SECURITY.md detailing the security model, threat model, authentication, transport security, network isolation, and incident response procedures. - Introduced SETUP.md providing a detailed setup guide for local and production environments, including prerequisites, environment setup, and Gitea integration. - Added STREAMING.md outlining the streaming pipeline, including production flow, source-media contract, playout and HLS packaging, cache contract, player behavior, and monitoring. - Updated architecture documentation to include links to new SETUP.md and STREAMING.md files for better navigation.
5.3 KiB
5.3 KiB
DEVELOPMENT.md — Linear Void Remaining Tasks
Test Fixtures (BLOCKED — requires ffmpeg)
-
Create test media fixtures in
backend/playout/testdata/:valid_720p30.mp4— small (1-2s) H.264/AAC compliant fileinvalid_h265.mp4— wrong codecinvalid_24fps.mp4— wrong framerate- Generate via
ffmpegcommands documented in test file headers
-
Create test playlist fixtures in
backend/playout/testdata/:valid_playlist.txt,empty_playlist.txt,comments_only.txt,mixed_valid_invalid.txt
User Frontend Tests
- Video player behavior (play, pause, seek, buffering, error handling)
- Chat functionality (send/receive messages, presence, rate limiting, moderation)
- State management and data flow
- Responsive design and layout across different screen sizes
- Accessibility testing (keyboard navigation, screen reader support)
- Integration with backend APIs (mocking API responses for testing)
- Test coverage for all critical frontend components and interactions
- Add code coverage reporting and enforce minimum coverage threshold in CI/CD pipeline
- Document test cases and expected outcomes
Admin Frontend Tests
- Playlist management UI (add/remove videos, reorder, normalize)
- User moderation tools (mute/ban/report users, view moderation logs)
- Metrics and monitoring dashboards (Prometheus/Grafana integration)
- State management and data flow
- Responsive design and layout across different screen sizes
- Accessibility testing (keyboard navigation, screen reader support)
- Integration with backend APIs (mocking API responses for testing)
- Test coverage for all critical admin UI components and interactions
- Add code coverage reporting and enforce minimum coverage threshold in CI/CD pipeline
- Document test cases and expected outcomes
Cloudflare R2 Integration Test
- Upload test HLS segments and manifests to R2 bucket
- Verify correct cache headers are applied (immutable segments, TTLs)
- Test retrieval of segments and manifests from R2 via Cloudflare edge
- Validate cache hit/miss behavior and performance metrics
- Ensure integration test can run in CI/CD pipeline with proper mocking/stubbing of R2 API
- Document test cases and expected outcomes
Cloudflare Configuration (manual — Cloudflare dashboard)
Evidence tracker:
docs/operations/cloudflare-uptimerobot-checklist.md
- Cloudflare Pages: link Gitea repo, build
cd frontend && npm run build, outputfrontend/dist - Tiered Cache: enable Smart Tiered Cache, validate
Cf-Cache-Status: HITfrom upper tier - WAF: enable OWASP Managed Ruleset, set to Simulate → review 48h → Block, enable Bot Fight Mode
- Rate limiting:
/api/admin/login+/api/admin/*→ 10 req/10s per IP, Challenge action - HTTPS/WSS: Always Use HTTPS, HSTS max-age=31536000 includeSubDomains preload, min TLS 1.2
- HTTPS/WSS: enforce at edge (Cloudflare) and origin (nginx), redirect HTTP → HTTPS
External Services
Evidence tracker:
docs/operations/cloudflare-uptimerobot-checklist.md
- UptimeRobot: add HTTP monitor for
https://linearvoid.tv/health(5min interval) - UptimeRobot: add keyword monitor for
https://linearvoid.tv/hls/playlist.m3u8(keyword:#EXTM3U, 5min) - Alert on 2 consecutive failures, notify via email + Discord/Slack webhook
Production Deployment (Hetzner — not provisioned)
- Provision Hetzner CX22 (2 vCPU, 4 GB, 40 GB) in Ashburn VA, Ubuntu 24.04
- Install Docker Engine + Compose plugin, open firewall: 80/443 (public), 2375 (runner IP only)
- Configure Docker daemon for remote TLS access (
-H tcp://0.0.0.0:2376with certs) - Create
/srv/linearvoid/data/{playlist,media,hls,chat,slate}directories - Add
CI_PROD_*secrets to Gitea: DOCKER_HOST, R2 keys, admin password, DB password, Grafana password - Trigger CD workflow with
DOCKER_HOSTpointing to Hetzner IP - Verify all 11 containers start healthy, check
/health,/hls/playlist.m3u8, WebSocket - Update Cloudflare A record
linearvoid.tv→ Hetzner IP, SSL Full (strict), test HTTPS + WSS - Smoke test: viewer SPA loads, HLS plays, chat connects, admin login → upload → playlist → playout
- Set up Prometheus alerting notifications + UptimeRobot on production URL
- Run
scripts/backup-db.sh+scripts/verify-backups.shon production host - Document production IP, SSH access, rollback procedure, scaling thresholds
Scaling & Performance (planning only)
- Tune manifest TTL: measure
Cf-Cache-Statusdistribution, adjust to 0.5× segment duration - Measure TTFB: WebPageTest from 3+ US regions, target <4s warm cache, document baseline
- Load-test WebSocket:
artilleryor Go script, ramp 10→100→500→1000 connections, measure p95 latency + errors - Benchmark admin API:
wrk/k6against/api/admin/*, target p95 <1s, identify slow queries - Track cache hit ratio: Cloudflare GraphQL → Grafana panel, alert <90%
- Capacity triggers: Prometheus rules for cache-miss >10%/15min, chat p95 >1s/5min, CPU >80%/10min
- Phase 2 plan: document boundaries (playout CPU, chat latency, DB state, monitoring), estimate per-service resources
- Phase 3 plan: research second Hetzner location, design warm standby + DNS failover + DB/Redis replication