140 lines
5.0 KiB
Markdown
140 lines
5.0 KiB
Markdown
# 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
|