add setup guide

2026-08-02 17:29:32 +02:00
1 parent 15043cb4d1
commit cb36cfa18d
@@ -0,0 +1,139 @@
+# Linear Void Setup Guide
+
+This guide covers prerequisites, environment setup, running the application locally and in production, and troubleshooting. It references the architecture documentation (`docs/architecture/README.md`) and ADRs in `docs/architecture/adr/`.
+
+## Prerequisites
+
+- **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 20+**: For frontend development (`cd frontend && npm run dev`).
+- **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).
+- **Hetzner Cloud Account** (optional for production): For the US-East VPS (Ashburn, VA recommended per ADR-001).
+
+## Environment Setup
+
+1. **Clone the Repository** (if not already done):
+
+   ```bash
+   git clone <repository-url>
+   cd linearvoid
+   ```
+
+2. **Copy Environment File**:
+
+   ```bash
+   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
+
+   # Cloudflare (for custom domain and cache rules)
+   CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
+   MEDIA_DOMAIN=media.example.com
+
+   # Chat / Database
+   REDIS_URL=redis://redis:6379/0
+   DATABASE_URL=sqlite://./data/chat.db   # or postgres://user:pass@db:5432/linearvoid
+
+   # Ports (for local development)
+   CHAT_PORT=3000
+   NGINX_PORT=8080
+   PLAYOUT_HEALTH_PORT=8081
+
+   # Playout Configuration
+   PLAYLIST_PATH=/app/playlist/playlist.txt
+   HLS_SEGMENT_DURATION=6
+   HLS_WINDOW_SIZE=24
+
+   # Logging
+   LOG_LEVEL=info
+   ```
+
+4. **Create Data Directories**:
+
+   ```bash
+   mkdir -p data/playlist data/media data/hls data/chat
+   ```
+
+5. **Prepare Sample Videos** (optional):
+   - Place normalized MP4 files in `data/media/`.
+   - Create a `data/playlist/playlist.txt` with paths (see ADR-001 for normalization requirements).
+
+## Running the Application
+
+### Local Development
+
+1. **Start All Services**:
+
+   ```bash
+   docker compose up --build
+   ```
+
+2. **Access the Application**:
+   - Viewer: <http://localhost:8080>
+   - Chat WebSocket: ws://localhost:3000/ws
+   - Admin Interface: <http://localhost:8080/admin> (use the credentials from `.env` or default admin/admin)
+   - Health Checks:
+     - Playout: <http://localhost:8081/health>
+     - Chat: <http://localhost:3000/health>
+   - Monitoring:
+     - Prometheus: <http://localhost:9090>
+     - Grafana: <http://localhost:3001> (default login: admin/admin)
+
+3. **Frontend Development** (optional, for UI changes):
+
+   ```bash
+   cd frontend
+   npm run dev
+   ```
+
+   The dev server runs on <http://localhost:5173>. It proxies API calls to the backend services.
+
+4. **Stop Services**:
+
+   ```bash
+   docker compose down
+   ```
+
+### Production Deployment (Hetzner VPS + Cloudflare)
+
+1. **Provision VPS**: Use Hetzner Cloud CX22 in Ashburn, VA (per ADR-001).
+2. **Configure Cloudflare**:
+   - Create R2 bucket with `enam` location hint.
+   - Set up custom domain (`media.example.com`) with the cache rules from `infrastructure/cloudflare/cache-rules.md`.
+   - Apply the Worker from `infrastructure/cloudflare/worker.js` for advanced header management.
+3. **Deploy**:
+   - Copy the project to the VPS.
+   - Run `docker compose up -d --build`.
+   - Configure systemd to manage the Docker Compose stack.
+4. **Monitoring**: Access Grafana at the exposed port for dashboards (included in `monitoring/grafana/dashboard.json`).
+
+See `docs/architecture/README.md` for the full arc42 documentation and the ADRs for architectural decisions.
+
+## Troubleshooting
+
+- **R2 Upload Fails**: Check credentials in `.env` and ensure the bucket exists. Verify with `aws s3 ls --endpoint-url=$R2_ENDPOINT`.
+- **Normalization Errors**: Run `backend/playout/start-playout.sh` manually to see ffprobe output. All videos must be H.264/AAC, 30 fps constant, 2s keyframes (ADR-001).
+- **Chat Not Connecting**: Check Redis connection and WebSocket URL. The health check at `/health` should return 200.
+- **Cache Not Working**: Verify Cloudflare cache rules (`.ts` = long TTL immutable, `.m3u8` = short TTL). Check cache hit ratio in Cloudflare dashboard.
+- **Docker Issues**: Run `docker compose logs` for service-specific errors. Ensure ports are not in use.
+- **Admin Interface**: Ensure the protected route is configured in nginx and authentication is set up (default is open for local development).
+
+## Further Reading
+
+- Architecture: `docs/architecture/README.md` (arc42 template with diagrams).
+- Decisions: `docs/architecture/adr/` (ADR-001 to ADR-007).
+- Contributing: `CONTRIBUTING.md`.
+- 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-02