fix: improve CI workflows and README documentation

2026-08-04 16:58:05 +02:00
1 parent 8f1e227d50
commit 693b4a42f6
@@ -7,6 +7,8 @@
 [![Build Status](https://git.allucanget.biz/zwitschi/linearvoid/actions/workflows/ci.yml/badge.svg)](https://git.allucanget.biz/zwitschi/linearvoid/actions)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![Gitea](https://img.shields.io/badge/Gitea-1.27.1-blue)](https://git.allucanget.biz)
+[![Version](https://img.shields.io/badge/version-1.0.3-blue)](https://git.allucanget.biz/zwitschi/linearvoid/releases)
+[![Release Notes](https://img.shields.io/badge/release-notes-green)](CHANGELOG.md)

 ## Architecture

@@ -27,6 +29,23 @@ See [`docs/architecture/adr/`](docs/architecture/adr/) for the full set of decis
 - Video normalization, monitoring, fallback slate, and easy playlist management.
 - US-centric performance (Ashburn origin + Cloudflare POPs).

+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    V[US Viewers] -->|HTTPS| CF[Cloudflare CDN]
+    CF -->|Cache HIT| R2[Cloudflare R2]
+    CF -->|Cache MISS| N[Nginx :80]
+    N -->|/ws| CH[Chat :3000]
+    N -->|/admin| CH
+    N -->|/hls| P[Playout :8081]
+    N -->|/*| FE[Frontend SPA]
+    CH --> R[(Redis)]
+    CH --> DB[(PostgreSQL)]
+    P -->|ffmpeg| HLS[/data/hls/]
+    P -->|sync| R2
+```
+
 ## Project Structure

 ```text
@@ -97,9 +116,16 @@ This structure directly reflects the building blocks, runtime flows, deployment
 git clone https://git.allucanget.biz/zwitschi/linearvoid.git
 cd linearvoid
 cp .env.example .env
+# Edit .env with your R2 credentials and domain settings
 docker compose up --build
 ```

+Then open:
+
+- **Viewer**: [https://linearvoid.tv](https://linearvoid.tv) (or `http://localhost`)
+- **Admin**: [https://linearvoid.tv/admin](https://linearvoid.tv/admin) (or `http://localhost/admin`)
+- **Metrics**: [https://linearvoid.tv/metrics](https://linearvoid.tv/metrics)
+
 Full setup guide: [`SETUP.md`](SETUP.md).

 See the [architecture docs](docs/architecture/README.md) for detailed architecture and ADRs.
@@ -111,6 +137,50 @@ See the [architecture docs](docs/architecture/README.md) for detailed architectu
 - Normalize all source videos before adding to playlist (see ADR-001 for exact codec/fps/keyframe requirements).
 - Monitor cache hit ratio and R2 operations closely — they determine real cost.

+### Environment Variables
+
+| Variable               | Default                                         | Description                      |
+| ---------------------- | ----------------------------------------------- | -------------------------------- |
+| `R2_ACCESS_KEY_ID`     | —                                               | Cloudflare R2 access key         |
+| `R2_SECRET_ACCESS_KEY` | —                                               | Cloudflare R2 secret key         |
+| `R2_BUCKET_NAME`       | `linearvoid-media`                              | R2 bucket for HLS segments       |
+| `DATABASE_URL`         | `postgres://...@db:5432/...`                    | Chat DB (Postgres or SQLite)     |
+| `REDIS_URL`            | `redis://redis:6379/0`                          | Redis for presence/rate limiting |
+| `VITE_PUBLIC_APP_URL`  | `https://linearvoid.tv`                         | Public viewer URL                |
+| `VITE_PUBLIC_WS_URL`   | `wss://linearvoid.tv/ws`                        | WebSocket endpoint               |
+| `VITE_PUBLIC_HLS_URL`  | `https://media.linearvoid.tv/hls/playlist.m3u8` | HLS playlist URL                 |
+| `ADMIN_USERNAME`       | `admin`                                         | Admin panel username             |
+| `ADMIN_PASSWORD`       | —                                               | Admin panel password             |
+| `HLS_SEGMENT_DURATION` | `6`                                             | HLS segment duration in seconds  |
+| `HLS_WINDOW_SIZE`      | `24`                                            | HLS playlist window size         |
+
+Full reference: [`.env.example`](.env.example).
+
+### Troubleshooting
+
+| Problem                  | Check                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------- |
+| **Playout not starting** | Verify playlist exists in `data/playlist/playlist.txt` and media files are accessible |
+| **HLS not playing**      | Check `docker compose logs playout` for ffmpeg errors; verify `data/hls/` permissions |
+| **Chat not connecting**  | Ensure Redis is running: `docker compose logs redis`; check `DATABASE_URL`            |
+| **Admin panel 401**      | Verify `ADMIN_USERNAME`/`ADMIN_PASSWORD` in `.env` match login credentials            |
+| **Docker build fails**   | Run `docker compose build --no-cache`; check `backend/playout/.dockerignore`          |
+| **R2 upload failures**   | Verify `R2_ACCESS_KEY_ID` and `R2_SECRET_ACCESS_KEY`; check bucket CORS settings      |
+
+### API Endpoints
+
+| Service     | Endpoint                 | Description                |
+| ----------- | ------------------------ | -------------------------- |
+| **Chat**    | `GET /health`            | Health check               |
+| **Chat**    | `GET /metrics`           | Prometheus metrics         |
+| **Chat**    | `GET /ws`                | WebSocket upgrade for chat |
+| **Chat**    | `GET /api/admin/*`       | Admin API (auth required)  |
+| **Chat**    | `POST /api/admin/login`  | Admin login                |
+| **Playout** | `GET /health`            | Health check (port 8081)   |
+| **Nginx**   | `GET /`                  | Viewer SPA                 |
+| **Nginx**   | `GET /admin/`            | Admin panel                |
+| **Nginx**   | `GET /hls/playlist.m3u8` | HLS manifest               |
+
 ## Architecture Documentation

 The architecture is fully documented using the [arc42 template](docs/architecture/README.md) (with populated sections, Mermaid context and building-block diagrams, deployment view, cross-cutting concepts, quality goals, risks, and glossary).
@@ -141,4 +211,17 @@ Contributions, issues, and further evolution (LL-HLS, ABR, multi-channel, E2EE)

 **Container Registry**: `git.allucanget.biz/zwitschi/linearvoid/<service>:latest`

+## Contributing
+
+Contributions are welcome! See [`CONTRIBUTING.md`](CONTRIBUTING.md) for guidelines. Quick overview:
+
+1. Read the [architecture docs](docs/architecture/README.md) and ADRs first.
+2. Plan tasks in `.github/instructions/TODO.md`.
+3. Open PRs on [Gitea](https://git.allucanget.biz/zwitschi/linearvoid).
+4. CI validates builds and tests automatically.
+
+Since this a linear project, we also rely on a linear development and release model: Only main branch is used for releases, and all features are merged into main after review and CI validation. Releases are tagged with semantic versioning (v1.0.3, v1.0.4, etc.) and automatically built/pushed to the container registry.
+
+[MIT License](LICENSE)
+
 The project is ready for use. See [`SETUP.md`](SETUP.md) for detailed installation instructions.