From 80c1f4acce811dd8960b5629ad1c2e3490919cd9 Mon Sep 17 00:00:00 2001 From: zwitschi Date: Sun, 2 Aug 2026 18:17:08 +0200 Subject: [PATCH] update CI/CD workflows, fix YAML formatting, and enhance documentation with ADR references --- .gitea/workflows/cd.yml | 2 +- .gitea/workflows/ci.yml | 2 +- .gitea/workflows/dependency-updates.yml | 20 ++++----- .gitea/workflows/release.yml | 2 +- CONTRIBUTING.md | 7 +++ README.md | 58 ++++++++++++++++++++----- docs/architecture/README.md | 15 ++++--- 7 files changed, 77 insertions(+), 29 deletions(-) diff --git a/.gitea/workflows/cd.yml b/.gitea/workflows/cd.yml index 35a2e4f..8fb629f 100644 --- a/.gitea/workflows/cd.yml +++ b/.gitea/workflows/cd.yml @@ -7,7 +7,7 @@ on: jobs: deploy: - runs-on: [self-hosted, linux, docker] + runs-on: [self-hosted, linux, docker, ubuntu-latest] environment: production steps: - name: Checkout code diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml index b38e82c..6f38d13 100644 --- a/.gitea/workflows/ci.yml +++ b/.gitea/workflows/ci.yml @@ -8,7 +8,7 @@ on: jobs: test: - runs-on: [self-hosted, linux, docker] + runs-on: [self-hosted, linux, docker, ubuntu-latest] steps: - name: Checkout code uses: actions/checkout@v4 diff --git a/.gitea/workflows/dependency-updates.yml b/.gitea/workflows/dependency-updates.yml index 8e50f31..4d57d5d 100644 --- a/.gitea/workflows/dependency-updates.yml +++ b/.gitea/workflows/dependency-updates.yml @@ -2,12 +2,12 @@ name: Dependency Updates on: schedule: - - cron: '0 2 * * 1' # Every Monday at 2 AM UTC + - cron: "0 2 * * 1" # Every Monday at 2 AM UTC workflow_dispatch: jobs: update-dependencies: - runs-on: [self-hosted, linux, docker] + runs-on: [self-hosted, linux, docker, ubuntu-latest] steps: - name: Checkout code uses: actions/checkout@v4 @@ -18,8 +18,8 @@ jobs: - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version: '20' - cache: 'npm' + node-version: "20" + cache: "npm" cache-dependency-path: frontend/package-lock.json - name: Update Frontend Dependencies @@ -31,7 +31,7 @@ jobs: - name: Setup Go uses: actions/setup-go@v5 with: - go-version: '1.22' + go-version: "1.22" cache: true - name: Update Go Dependencies @@ -43,16 +43,16 @@ jobs: uses: peter-evans/create-pull-request@v5 with: token: ${{ secrets.GITEA_TOKEN }} - commit-message: 'chore: update dependencies' - title: 'chore: weekly dependency updates' + commit-message: "chore: update dependencies" + title: "chore: weekly dependency updates" body: | Automated weekly dependency updates. - + This PR updates: - Frontend npm dependencies - Go module dependencies - + Please review the changes and ensure tests pass before merging. branch: dependency-updates delete-branch: true - labels: dependencies, automated \ No newline at end of file + labels: dependencies, automated diff --git a/.gitea/workflows/release.yml b/.gitea/workflows/release.yml index c95c1bc..3b70ce7 100644 --- a/.gitea/workflows/release.yml +++ b/.gitea/workflows/release.yml @@ -13,7 +13,7 @@ on: jobs: release: - runs-on: [self-hosted, linux, docker] + runs-on: [self-hosted, linux, docker, ubuntu-latest] steps: - name: Checkout code uses: actions/checkout@v4 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 556e72a..f7fc003 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,6 +11,12 @@ Thank you for considering contributing to Linear Void! 5. **Commit Messages**: Reference the relevant ADR (e.g., "feat(playout): add R2 sync per ADR-001"). 6. **Test with Docker**: Run `docker compose up --build` to test changes. +## Repository + +- **Primary**: [git.allucanget.biz/zwitschi/linearvoid](https://git.allucanget.biz/zwitschi/linearvoid) +- **Container Registry**: `git.allucanget.biz/zwitschi/linearvoid/:latest` +- **CI/CD**: Gitea Actions with self-hosted runners (see `.gitea/workflows/`) + ## Code Style - Go: Use standard formatting (`go fmt`). @@ -19,6 +25,7 @@ Thank you for considering contributing to Linear Void! ## Pull Requests +- Open PRs on [Gitea](https://git.allucanget.biz/zwitschi/linearvoid). - Reference the related ADR in the PR description. - Ensure all tests pass and documentation is updated. - The CI workflow will validate normalization, linting, and Docker builds. diff --git a/README.md b/README.md index 8693c49..3a6d045 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,22 @@ A self-managed **24/7 linear video channel** for a primarily US audience. It runs a continuous playlist of self-owned videos with true/near-true synchronization, a custom lightweight viewer SPA (hls.js player + chat), and full independence from third-party platforms (YouTube, Twitch, etc.). +**Repository**: [git.allucanget.biz/zwitschi/linearvoid](https://git.allucanget.biz/zwitschi/linearvoid) + +[![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) + +## Architecture + The architecture (detailed in [`docs/architecture/README.md`](docs/architecture/README.md)) uses: - Hetzner Ashburn VPS for playout (FFmpeg + MediaMTX/SRS) and chat. - Cloudflare R2 + CDN with aggressive immutable caching of HLS `.ts` segments ($0 egress). - Lightweight static frontend and WebSocket chat backend. +- Gitea self-hosted CI/CD (Actions) and Container Registry. -See [`docs/architecture/adr/ADR-001.md`](docs/architecture/adr/ADR-001.md) for the consolidated decision record, storage calculations, cache rules, cost model, and implementation plan. +See [`docs/architecture/adr/`](docs/architecture/adr/) for the full set of decision records (ADR-001 through ADR-007) covering architecture, storage calculations, cache rules, cost model, module structure, tech stack, admin interfaces, data storage, and caching strategy. ## Key Features @@ -55,7 +64,13 @@ linearvoid/ │ └── architecture/ │ ├── README.md # arc42 template (fully populated) │ └── adr/ -│ └── ADR-001.md # Consolidated decision record +│ ├── ADR-001.md # Consolidated decision record +│ ├── ADR-002-module-structure.md +│ ├── ADR-003-tech-stack.md +│ ├── ADR-004-admin-video.md +│ ├── ADR-005-admin-moderation-analytics.md +│ ├── ADR-006-data-storage.md +│ └── ADR-007-redis-usage.md ├── .env.example ├── .gitignore ├── docker-compose.yml # Top-level for dev (playout + chat + nginx) @@ -72,17 +87,22 @@ linearvoid/ - **`infrastructure/`**: Everything needed to deploy and configure the stack (Docker, Nginx, Cloudflare rules, future Terraform). - **`scripts/`**: One-off and CI-friendly scripts for video preparation, R2 sync, backups, and playlist management. - **`monitoring/`**: Grafana dashboards, Prometheus rules, logging configuration. -- **`docs/architecture/`**: Complete arc42 documentation + ADR-001 (the single source of truth for all architectural decisions). +- **`docs/architecture/`**: Complete arc42 documentation + ADRs 001-007 (the single source of truth for all architectural decisions). This structure directly reflects the building blocks, runtime flows, deployment view, and cross-cutting concepts defined in the arc42 documentation. ## Getting Started -1. `cp .env.example .env` and configure secrets (R2 keys, Cloudflare, etc.). -2. Prepare normalized videos (`scripts/normalize-video.sh`). -3. Run locally: `docker compose up` (or individual services). -4. Deploy: Provision Hetzner VPS, push to R2, configure Cloudflare cache rules (see `infrastructure/cloudflare/` and ADR-001). -5. Full setup and operational runbooks are in the [architecture docs](docs/architecture/README.md). +```bash +git clone https://git.allucanget.biz/zwitschi/linearvoid.git +cd linearvoid +cp .env.example .env +docker compose up --build +``` + +Full setup guide: [`SETUP.md`](SETUP.md). + +See the [architecture docs](docs/architecture/README.md) for detailed architecture and ADRs. ## Development @@ -98,10 +118,26 @@ The architecture is fully documented using the [arc42 template](docs/architectur - **[ADR-001](docs/architecture/adr/ADR-001.md)**: Overall system architecture, HLS + Cloudflare R2 caching strategy, storage calculations, cost model, risks, and implementation plan. - **[ADR-002](docs/architecture/adr/ADR-002-module-structure.md)**: Chosen project folder/module structure (frontend, backend/playout, backend/chat, infrastructure, scripts, monitoring) and mapping to arc42 building blocks. -- **[ADR-003](docs/architecture/adr/ADR-003-tech-stack.md)**: Technology stack, language choices per module (TypeScript for frontend, Go preferred for chat and playout wrapper, Bash/Python for scripts), Docker-first approach, and all implicit assumptions (mandatory video normalization, Cloudflare-centric delivery, monitoring focus, etc.). - -These three ADRs together provide complete traceability for all major design decisions. Future ADRs will cover Docker Compose layout, API contracts, monitoring strategy, and access control. +- **[ADR-003](docs/architecture/adr/ADR-003-tech-stack.md)**: Technology stack, language choices per module (TypeScript for frontend, Go preferred for chat and playout wrapper, Bash/Python for scripts), Docker-first approach, and all implicit assumptions. +- **[ADR-004](docs/architecture/adr/ADR-004-admin-video.md)**: Video admin web interface (upload, playlist management, schedule overrides, normalization enforcement). +- **[ADR-005](docs/architecture/adr/ADR-005-admin-moderation-analytics.md)**: Web admin interfaces for user management, moderation dashboard, analytics, and system configuration. +- **[ADR-006](docs/architecture/adr/ADR-006-data-storage.md)**: Data storage strategy (SQLite vs PostgreSQL for v1, migration path, admin interface capabilities). +- **[ADR-007](docs/architecture/adr/ADR-007-redis-usage.md)**: Redis usage (exact use cases, TTL policies, persistence, fallback behavior, admin configuration). See the [architecture README](docs/architecture/README.md) for the big-picture view and the individual ADR files for detailed rationale, alternatives, and consequences. Contributions, issues, and further evolution (LL-HLS, ABR, multi-channel, E2EE) should reference the architecture documentation. + +## Resources + +- [CHANGELOG.md](CHANGELOG.md) - Version history and completed features. +- [CONTRIBUTING.md](CONTRIBUTING.md) - Guidelines for contributing to the project. +- [SETUP.md](SETUP.md) - Complete setup guide with prerequisites, environment configuration, running the application, and troubleshooting. +- [Architecture Documentation](docs/architecture/README.md) - Full arc42 template with diagrams and decisions. +- [ADRs](docs/architecture/adr/) - Detailed decision records (ADR-001 to ADR-007). + +**CI/CD**: [View workflows](https://git.allucanget.biz/zwitschi/linearvoid/actions) on Gitea Actions. + +**Container Registry**: `git.allucanget.biz/zwitschi/linearvoid/:latest` + +The project is ready for use. See [`SETUP.md`](SETUP.md) for detailed installation instructions. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 2d10985..0bd6674 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -274,17 +274,22 @@ The primary decisions are captured in the following consolidated ADRs (all locat - **[ADR-001](./adr/ADR-001.md)**: Overall architecture, HLS + Cloudflare R2 caching strategy, storage calculations, cost model, risks. - **[ADR-002](./adr/ADR-002-module-structure.md)**: Chosen project folder/module structure (frontend, backend/playout, backend/chat, infrastructure, scripts, monitoring) and rationale. -- **[ADR-003](./adr/ADR-003-tech-stack.md)**: Technology stack, programming language choices per module (TypeScript frontend, Go for chat/playout wrapper, Bash/Python scripts), Docker-first approach, and explicit documentation of all implicit assumptions (normalization requirement, Cloudflare-centric delivery, monitoring focus, etc.). +- **[ADR-003](./adr/ADR-003-tech-stack.md)**: Technology stack, programming language choices per module (TypeScript frontend, Go for chat/playout wrapper, Bash/Python scripts), Docker-first approach, and explicit documentation of all implicit assumptions. +- **[ADR-004](./adr/ADR-004-admin-video.md)**: Video admin web interface (upload, playlist management, schedule overrides, normalization enforcement). +- **[ADR-005](./adr/ADR-005-admin-moderation-analytics.md)**: Web admin interfaces for user management, moderation dashboard, analytics, and system configuration. +- **[ADR-006](./adr/ADR-006-data-storage.md)**: Data storage strategy (SQLite vs PostgreSQL for v1, migration path, admin interface capabilities). +- **[ADR-007](./adr/ADR-007-redis-usage.md)**: Redis usage (exact use cases, TTL policies, persistence, fallback behavior, admin configuration). -These ADRs together form the canonical decision log. Future ADRs (e.g., Docker Compose layout, API contracts, monitoring strategy) will be added to the same folder and referenced here. +These ADRs together form the canonical decision log. -**Summary of Key Decisions** (from ADR-001/002/003): +**Summary of Key Decisions** (from ADR-001 through ADR-007): - Self-managed US-East playout (Hetzner Ashburn) with FFmpeg + MediaMTX/SRS → HLS → Cloudflare R2 + edge caching. - Module structure that directly reflects the arc42 building blocks and context diagram. - Go preferred for performance-critical services; TypeScript for frontend; Docker for all deployment. - -See the individual ADR files for full context, alternatives considered, consequences, and references. +- Admin interfaces for video management, moderation, analytics, and system configuration using HTMX + Tailwind. +- SQLite as primary database for v1 with PostgreSQL migration path if needed. +- Redis for rate limiting, presence, pub/sub, session storage with defined TTL policies and fallback behavior. ## Quality Requirements