git-pages helm chart

2026-06-10 05:18:58 +03:00
parent 14cf2eaeed
commit 26a8b9efa8
29 changed files with 2610 additions and 0 deletions
@@ -0,0 +1,143 @@
+# Architecture — git-pages
+
+> Komponentit, datavirrat ja rajapinnat. Miksi näin on rakennettu: [design-rationale.md](design-rationale.md).
+> Secretit: [secrets.md](secrets.md). Teknologiat: [tech-stack.md](tech-stack.md).
+
+Tämä dokumentti koskee vain `git-pages/`-palvelua — ei juuren `gitea-ci-library`-kirjastoa.
+
+---
+
+## Yleiskuvaus
+
+git-pages on jaettu **HTML-raporttiarkisto**: yksi apex-host, monta Gitea-repoa, commit-kohtaiset
+raporttipolut. Julkaisija (esim. CI) puskaa sisällön tar-arkistona; lukija avaa raportin
+selaimella commit-linkistä.
+
+Codeberg git-pages ajaa `PAGES_INSECURE=1` — sovellus ei tee forge-authia. Julkaisu- ja
+TLS-rajaukset ovat Kubernetes-kerroksessa (Traefik, cert-manager, Secretit).
+
+---
+
+## Komponentit
+
+| Komponentti | Rooli |
+|-------------|-------|
+| **git-pages Pod** | Codeberg git-pages `0.9.1`, filesystem-storage `/app/data` |
+| **PVC** | Raporttisisältö (`{owner}/{repo}/reports/{sha8}/…`) |
+| **Service** | ClusterIP :3000 git-pagesille |
+| **Traefik IngressRoute** | Julkaisu (PATCH/PUT + BasicAuth) ja luku (GET/HEAD) eri säännöillä |
+| **Traefik Middleware** | `git-pages-publish-auth` (BasicAuth), HTTPS-redirect |
+| **cert-manager Certificate** | TLS → Secret `git-pages-tls` |
+| **CronJob `git-pages-retention`** | Päivittäinen siivous (PVC + Gitea branch-lista) |
+
+| Secret | Rooli |
+|--------|-------|
+| `git-pages-publish-auth` | htpasswd julkaisuun (Traefik) |
+| `git-pages-retention-gitea` | Gitea PAT branch-listaan (CronJob) |
+
+---
+
+## URL ja sisältö
+
+Julkinen osoite = **selvä URL** + **Gitea-yhteensopiva polku**:
+
+```
+https://pages.example.com/acme-corp/backend-api/reports/abc12345/index.html
+         └─ selvä URL ─┘ └────────── Gitea-yhteensopiva polku ──────────┘
+```
+
+Levyllä (apex index-site):
+
+```
+/app/data/
+  {owner}/
+    {repo}/
+      reports/
+        {sha8}/
+          index.html
+          .meta          # branch, sha, published_at
+```
+
+Apex-juuri `/` on tyhjä — ei landing-sivua.
+
+---
+
+## Järjestelmäkaavio
+
+```mermaid
+flowchart TB
+    subgraph ext["Ulkoiset"]
+        PUB["Julkaisija\n(CI)"]
+        BR["Selain"]
+        GITEA["Gitea API\n(branch-lista)"]
+    end
+
+    subgraph edge["Reuna"]
+        TRAEFIK["Traefik\nIngressRoute + Middleware"]
+        CM["cert-manager\nTLS"]
+    end
+
+    subgraph cluster["git-pages"]
+        GP["git-pages Pod"]
+        PVC["PVC /app/data"]
+        CJ["CronJob retention"]
+    end
+
+    PUB -->|"PATCH/PUT + BasicAuth\ntar"| TRAEFIK
+    BR -->|"GET/HEAD"| TRAEFIK
+    TRAEFIK --> GP
+    CM --> TRAEFIK
+    GP --> PVC
+    CJ -->|"read branches"| GITEA
+    CJ --> PVC
+```
+
+---
+
+## Julkaisu
+
+1. Julkaisija paketoi `{owner}/{repo}/reports/{sha8}/` tar-arkistoksi (sis. `.meta`)
+2. `PATCH` tai `PUT` apex-URL:iin (`https://{host}/`) + `Content-Type: application/x-tar`
+3. Traefik tarkistaa BasicAuth (`publish` + token) → välittää git-pagesille
+4. git-pages kirjoittaa PVC:lle
+
+Julkaisu kulkee aina julkisen ingressin kautta — ei suoraa ClusterIP-kirjoitusta ulkopuolelta.
+
+---
+
+## Luku
+
+1. Selain avaa commit-statuslinkin (GET/HEAD)
+2. Traefik välittää git-pagesille ilman julkaisu-Middlewarea
+3. git-pages palauttaa HTML:n polusta
+
+Luku-auth (OIDC) ei ole toteutettu — GET/HEAD on julkinen, jos URL tunnetaan.
+Katso [design-rationale.md — Luku-auth](design-rationale.md#luku-auth).
+
+---
+
+## Retention
+
+CronJob `git-pages-retention` (oletus kerran päivässä):
+
+1. Skaalaa git-pages deployment hetkeksi pois (RWO-PVC)
+2. Käy läpi `reports/{sha8}/.meta`
+3. **Poistettu branch** — jos `.meta.branch` ei ole Gitean branch-listassa → poista (aina)
+4. **Aktiivinen branch** — `maxAgeDays` + `keepMin` (`retention.rules` instanssiarvoissa)
+5. Skaalaa deployment takaisin
+
+Gitea API: `GET /api/v1/repos/{owner}/{repo}/branches` — `read:repository` PAT.
+Katso [secrets.md](secrets.md).
+
+---
+
+## Rajapinnat
+
+| Suunta | Protokolla | Auth | Kuvaus |
+|--------|------------|------|--------|
+| Julkaisija → Traefik | HTTPS PATCH/PUT | BasicAuth `publish` | tar → apex site |
+| Selain → Traefik | HTTPS GET/HEAD | — (tänään) | HTML-raportti |
+| CronJob → Gitea | HTTPS GET | PAT `read:repository` | branch-lista per repo |
+| Traefik → git-pages | HTTP :3000 | — | sisäverkko |
+
+git-pages ei käytä Gitea forge-API:a julkaisuun eikä `pages`-branchia.