feat: add automatic media normalization, R2 retention cleanup, and seamless playout loops

2026-08-13 11:59:46 +02:00
1 parent e15d89edfe
commit 06ab5b4655
@@ -1,5 +1,7 @@
 # Linear Void Setup Guide

+**Last Updated**: 2026-08-03
+
 This guide covers prerequisites, environment setup, running the application locally and in production, and troubleshooting. It references the [architecture documentation](./docs/architecture/README.md)(`docs/architecture/README.md`).

 ## Prerequisites
@@ -7,7 +9,7 @@ This guide covers prerequisites, environment setup, running the application loca
 - **Docker & Docker Compose**: Required for running the full stack (playout, chat, nginx, redis, db, prometheus, grafana). Install from [docker.com](https://www.docker.com).
 - **Node.js 22+**: Required for frontend development and production builds (`cd frontend && npm install && npm run build`).
 - **npm**: Installed with Node.js and used for the frontend dependency installation and Vite workflow.
- **Go 1.23+**: Recommended when working on the Go services outside Docker (`backend/chat`, `backend/playout`).
+- **Go 1.25+**: Recommended when working on the Go services outside Docker (`backend/chat`, `backend/playout`).
 - **FFmpeg**: Used by the playout service for HLS generation. Install via `apt install ffmpeg` (Linux), Homebrew (macOS), or Winget (Windows).
 - **Git**: For cloning and version control.
 - **Cloudflare Account**: For R2 storage and CDN (free tier sufficient for most use cases).
@@ -81,70 +83,7 @@ flowchart LR
   cp .env.example .env
   ```

-3. **Configure `.env`** (edit with your values):
-
-   ```env
-   # Cloudflare R2 (required for video storage and $0 egress)
-   R2_ACCESS_KEY_ID=your-r2-access-key
-   R2_SECRET_ACCESS_KEY=your-r2-secret-key
-   R2_BUCKET_NAME=linearvoid-media
-   R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
-   R2_REGION=auto
-
-   # Cloudflare (for custom domain and cache rules)
-   CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
-   CLOUDFLARE_ACCOUNT_ID=your-account-id
-   MEDIA_DOMAIN=media.linearvoid.tv
-
-   # Public frontend URLs
-   # Preferred local setup uses the real public domains through Cloudflare and Nginx Proxy Manager.
-   VITE_PUBLIC_APP_URL=https://linearvoid.tv
-   VITE_PUBLIC_WS_URL=wss://linearvoid.tv/ws
-   VITE_PUBLIC_HLS_URL=https://media.linearvoid.tv/hls/playlist.m3u8
-   VITE_PUBLIC_ADMIN_DEFAULT_MODERATOR=admin
-   VITE_PUBLIC_ADMIN_DEFAULT_ROOM=main
-   VITE_PUBLIC_ADMIN_MODERATION_LOG_LIMIT=50
-   ADMIN_USERNAME=admin
-   ADMIN_PASSWORD=change-me
-   ADMIN_SESSION_TTL_HOURS=12
-   # Optional direct-local fallback when bypassing the public proxy:
-   # VITE_PUBLIC_APP_URL=http://localhost
-   # VITE_PUBLIC_WS_URL=ws://localhost/ws
-   # VITE_PUBLIC_HLS_URL=http://localhost/hls/playlist.m3u8
-
-   # Gitea Container Registry (for self-hosted Docker images)
-   CI_REGISTRY_URL=git.allucanget.biz
-   CI_REGISTRY_USER=your-gitea-username
-   CI_REGISTRY_TOKEN=your-gitea-token
-   CI_REGISTRY_NAMESPACE=zwitschi/linearvoid
-   # Gitea API access (optional, for CI/release automation)
-   CI_SERVER_URL=https://git.allucanget.biz
-
-   # Chat / Database
-   DATABASE_URL=postgres://linearvoid:linearvoid@db:5432/linearvoid?sslmode=disable
-   # or for SQLite-only local development:
-   # DATABASE_URL=sqlite://./data/chat.db
-   REDIS_URL=redis://redis:6379/0
-
-   # Ports (for local development)
-   PLAYOUT_PORT=8080
-   CHAT_PORT=3000
-   NGINX_PORT=80
-
-   # Playout Configuration
-   PLAYLIST_PATH=/app/playlist.txt
-   HLS_SEGMENT_DURATION=6
-   HLS_WINDOW_SIZE=24
-
-   # Logging / Monitoring
-   LOG_LEVEL=info
-   PROMETHEUS_PORT=9090
-   GRAFANA_PORT=3001
-
-   # Development flags
-   NODE_ENV=development
-   GO_ENV=development
-   ```
+3. **Configure `.env`** (copy from `.env.example` and replace placeholders)

 4. **Check local value overrides for Docker Compose**:
   - `docker-compose.yml` builds images locally and maps the frontend build output from `frontend/dist` into nginx.
@@ -227,7 +166,23 @@ flowchart LR
   - Enable Smart Tiered Cache for the R2-backed hostname.
   - If you need header normalization for immutable segment caching, deploy `infrastructure/cloudflare/worker.js` to the same zone.

-7. **Verify access**:
+7. **Configure R2 CORS**:
+   - Add CORS rules to allow the app domain to access the R2 bucket for HLS delivery.
+   - Example CORS configuration:
+
+   ```json
+   [
+     {
+       "AllowedOrigins": ["https://linearvoid.tv"],
+       "AllowedMethods": ["GET"],
+       "AllowedHeaders": ["*"],
+       "ExposeHeaders": ["ETag", "Cache-Control"],
+       "MaxAgeSeconds": 3600
+     }
+   ]
+   ```
+
+8. **Verify access**:
   - Confirm uploads with an S3-compatible client such as `aws s3 ls --endpoint-url <R2_ENDPOINT>`.
   - After deployment, check Cloudflare analytics for cache hit ratio and origin request volume.

@@ -249,7 +204,8 @@ Execution tracker: `docs/operations/cloudflare-uptimerobot-checklist.md`.
 1. Create bucket `linearvoid-media`.
 2. Set location hint to `enam` (US-East).
 3. Attach custom domain `media.linearvoid.tv` to the bucket.
-4. Verify object read works from the custom domain.
+4. Configure CORS rules to allow `https://linearvoid.tv` for HLS delivery.
+5. Verify object read works from the custom domain.

 ### 3. Cache Rules

@@ -588,5 +544,3 @@ See `docs/architecture/README.md` for the full arc42 documentation and the ADRs
 - Project Structure: Root `README.md`.

 The system is ready for use. For production, review ADR-001 for cost estimates and scaling guidance.
-
-**Last Updated**: 2026-08-03