update CI/CD workflows, fix YAML formatting, and enhance documentation with ADR references
This commit is contained in:
zwitschi committed
1 parent
6995763ccb
commit
80c1f4acce
7 files changed
+77
-29
No files matched your search
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
labels: dependencies, automated
|
||||
@@ -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
|
||||
|
||||
@@ -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/<service>: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.
|
||||
|
||||
@@ -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)
|
||||
|
||||
[](https://git.allucanget.biz/zwitschi/linearvoid/actions)
|
||||
[](LICENSE)
|
||||
[](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/<service>:latest`
|
||||
|
||||
The project is ready for use. See [`SETUP.md`](SETUP.md) for detailed installation instructions.
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user