Feature/git pages -> oma nginx perusteinen raporointipalvelu (#48)

Co-authored-by: moilanik <niko.moilanen@tietoevry.com>
Reviewed-on: #48

gitea-reports/docs/secrets.md

@@ -0,0 +1,267 @@
+# Secrets — gitea-reports
+
+## Quick Start
+
+### Vaihe 1: Secret-arkkitehtuuri
+
+Järjestelmässä on kaksi loogista salaista arvoa. Publish-token jaetaan kahteen K8s-secretiin (Traefik-yhteensopivuus):
+
+| Looginen nimi | K8s | Gitea |
+|---|---|---|
+| `report_publish_api_token` (htpasswd) | `gitea-reports-publish-auth` (users) | - |
+| `report_publish_api_token` (plaintext) | `gitea-reports-publish-token` (token) | Actions Secret: `REPORTS_PUBLISH_TOKEN` |
+| `reports_retention_read_token` | `gitea-reports-retention-gitea` (token) | PAT: `CI-REPORTS_READ_FOR_RETENTION` |
+
+**Huomio:** Publish-token jaetaan kahteen secretiin, koska Traefik BasicAuth middleware vaatii single-key secretin sekä on muodossa, missä sitä ei saa takaisin. Jokainen repo mikä raportteja käyttää, tarvitsee selväkielisen arvon, joka on "ylimääräisessä" secretissä. 
+
+### Vaihe 2: Luo Gitea PAT (retention)
+
+**Avaa Gitea browserissa:**
+
+1. Kirjaudu Gitea-käyttäjällä, jolla on luku kaikkiin raporttirepoihin
+2. **Settings** → **Applications** → **Generate New Token**
+3. Token name: `CI-REPORTS_READ_FOR_RETENTION`
+4. Scopes: valitse vain **`read:repository`**
+5. **Generate Token** → **kopioi token heti** (näytetään vain kerran)
+6. Tallenna token talteen (`GITEA_RETENTION_TOKEN`)
+
+### Vaihe 3: Generoi publish-token
+
+**Palaa terminaalille:**
+
+```bash
+GITEA_RETENTION_TOKEN="<from Gitea>"
+
+REPORTS_PUBLISH_TOKEN="$(openssl rand -base64 24)"
+echo "Publish-token generoitu. Tallennetaan K8s-secretiin Vaiheessa 4."
+echo "$REPORTS_PUBLISH_TOKEN"
+```
+
+### Vaihe 4: Luo K8s secrets
+
+```bash
+NS=gitea-reports
+
+# 1. Publish-auth: htpasswd (Traefik BasicAuth - vaatii single-key secretin)
+kubectl create secret generic gitea-reports-publish-auth \
+  --from-literal=users="$(docker run --rm httpd:2-alpine htpasswd -nb publish "$REPORTS_PUBLISH_TOKEN")" \
+  -n "$NS"
+
+# 2. Publish-token: plaintext (luetaan README:stä Giteaan viedessä)
+kubectl create secret generic gitea-reports-publish-token \
+  --from-literal=token="$REPORTS_PUBLISH_TOKEN" \
+  -n "$NS"
+
+# 3. Retention (käyttää Vaiheessa 2 luotua PAT:ia)
+kubectl create secret generic gitea-reports-retention-gitea \
+  --from-literal=token="$GITEA_RETENTION_TOKEN" \
+  -n "$NS"
+
+kubectl get secrets -n "$NS"
+```
+
+---
+
+### Vaihe 5: Vie publish-token Gitea Actions-secretiin
+
+Token näkyy terminaalissa Vaiheen 3 `echo`sta. Jos se on jo kadonnut näkyvistä, hae se K8s-secretistä:
+
+```bash
+NS=gitea-reports
+kubectl get secret gitea-reports-publish-token -n "$NS" -o jsonpath='{.data.token}' | base64 -d; echo
+```
+
+Vie kopioitu secret Gitea Actions Secrets:
+
+Kannattaa viedä tämä token ORG tason secretiksi Gitea Actions. Muuten joudut tekemään tämän jokaiselle rapositorylle erikseen.
+
+Luo `REPORTS_PUBLISH_TOKEN` secret, ja terminaalista kopioitu arvo `values` kenttään. 
+
+Description voi olla esim: 
+> Julkaisuun liittyvä salaisuus, jonka gitea-pages auth tarkistaa, että saako julkaista raporttia.
+
+
+**Gitea UI:ssa:** New Secret → Name: `REPORTS_PUBLISH_TOKEN` → Value: **liitä token** → Save
+
+Toista jokaiselle repolle, joka julkaisee raportteja.
+
+---
+
+### Seuraava: Helm-asennus
+
+Palaa takaisin [README.md](../README.md#käyttöönotto) ja jatka kohdasta "Instanssin values-tiedosto".
+
+---
+
+## Secret Arkkitehtuuri
+
+### Loogiset salaisuudet
+
+| Looginen nimi | K8s | Gitea |
+|---|---|---|
+| `report_publish_api_token` | `gitea-reports-publish-auth` (htpasswd) | Actions Secret: `REPORTS_PUBLISH_TOKEN` |
+| `reports_retention_read_token` | `gitea-reports-retention-gitea` (token) | PAT: `CI-REPORTS_READ_FOR_RETENTION` |
+
+### Secret Reference Architecture
+
+```mermaid
+graph TD
+    subgraph "Publish Flow"
+        P1["Actions Secret<br/>REPORTS_PUBLISH_TOKEN"]
+        P2["K8s Secret<br/>gitea-reports-publish-auth"]
+        P1 -->|token| TRAEFIK
+        P2 -->|htpasswd| TRAEFIK
+        TRAEFIK["Traefik BasicAuth"]
+    end
+
+    subgraph "Retention Flow"
+        R1["K8s Secret<br/>gitea-reports-retention-gitea"]
+        R2["Gitea PAT<br/>CI-REPORTS_READ_FOR_RETENTION"]
+        R1 -->|token| SC["Sidecar"]
+        SC -->|API auth| GITEA["Gitea API"]
+        SC -->|read branches| GITEA
+    end
+```
+
+---
+
+## Data Flow
+
+### Flow 1: Julkaisu (Publish)
+
+```mermaid
+sequenceDiagram
+    participant Actions as Gitea Actions
+    participant Traefik as Traefik
+    participant K8sAuth as K8s Secret<br/>gitea-reports-publish-auth
+    participant K8sToken as K8s Secret<br/>gitea-reports-publish-token
+    participant Upload as upload-sidecar
+    participant PV as PVC /app/data
+
+    Note over Actions: 1. Lue plaintext-token
+    Actions->>K8sToken: lue token-avain
+    K8sToken-->>Actions: plaintext token
+
+    Note over Actions: 2. Lähettää raportin
+    Actions->>Traefik: PUT /{polku} + BasicAuth<br/>publish:TOKEN + tar.gz
+    Traefik->>K8sAuth: lue users (htpasswd)
+    K8sAuth-->>Traefik: publish:$apr1$...
+    alt Token match
+        Traefik->>Upload: PUT /{path}
+        Upload->>PV: extract tar.gz
+        PV-->>Upload: 201 Created
+        Upload-->>Traefik: 201 Created
+        Traefik-->>Actions: 201 Created
+    else Token ei match
+        Traefik-->>Actions: 401 Unauthorized
+    end
+```
+
+**Kaksi secretiä (Traefik-yhteensopivuus):**
+- `gitea-reports-publish-auth` = `users` (htpasswd, Traefik käyttää)
+- `gitea-reports-publish-token` = `token` (plaintext, luetaan Giteaan viedessä)
+
+---
+
+### Flow 2: Luku (Read)
+
+```mermaid
+sequenceDiagram
+    participant Browser as Selain
+    participant Traefik as Traefik
+    participant Nginx as nginx
+    participant PV as PVC /app/data
+
+    Browser->>Traefik: GET /OWNER/REPO/branch/SHA/suite/index.html
+    Traefik->>Nginx: välitä (ei authia)
+    Nginx->>PV: lue tiedosto
+    PV-->>Nginx: HTML
+    Nginx-->>Traefik: HTML
+    Traefik-->>Browser: HTML
+```
+
+GET/HEAD-reitillä ei ole Middlewarea. Luku on julkinen, jos URL tunnetaan.
+
+---
+
+### Flow 3: Retention (Siivous)
+
+```mermaid
+sequenceDiagram
+    participant CronJob as Retention CronJob
+    participant K8sSecret as K8s Secret<br/>gitea-reports-retention-gitea
+    participant GiteaAPI as Gitea API
+    participant PV as PVC /app/data
+
+    Note over CronJob: 1. Lue PAT
+    CronJob->>K8sSecret: lue token
+    K8sSecret-->>CronJob: Gitea PAT
+
+    Note over CronJob: 2. Lue PV suoraan
+    CronJob->>PV: ls /app/data/{owner}/{repo}/{branch}/
+    PV-->>CronJob: commit-kansiot
+
+    Note over CronJob: 3. Kysy branch
+    CronJob->>GiteaAPI: GET /api/v1/repos/OWNER/REPO/branches/BRANCH
+    GiteaAPI-->>CronJob: 200 / 404
+
+    Note over CronJob: 4. Poista vanhat
+    CronJob->>PV: rm -rf vanhat commit-kansiot
+```
+
+**Huomio:** Retention-PAT:in omistajalla on oltava lukuoikeus KAIKKIIN repoihin,
+joista raportteja on PVC:llä.
+
+---
+
+## Troubleshooting
+
+- **"secret not found"** — luiko secretit ennen Helm-asennusta?
+- **"401 Unauthorized"** — onko Gitea Actions secret oikea?
+- **"found 2 elements for secret"** — Traefik vaatii single-key secretin. Varmista että `gitea-reports-publish-auth` sisältää vain `users`-avaimen.
+- **"token hukkuu"** — generoi uusi token (Vaihe 3) ja päivitä molemmat publish-secretit:
+  ```bash
+  # 1. Generoi uusi
+  REPORTS_PUBLISH_TOKEN="$(openssl rand -base64 24)"
+
+  # 2. Päivitä K8s secrets (molemmat)
+  NS=gitea-reports
+  kubectl delete secret gitea-reports-publish-auth -n "$NS"
+  kubectl delete secret gitea-reports-publish-token -n "$NS"
+  
+  kubectl create secret generic gitea-reports-publish-auth \
+    --from-literal=users="$(docker run --rm httpd:2-alpine htpasswd -nb publish "$REPORTS_PUBLISH_TOKEN")" \
+    -n "$NS"
+  
+  kubectl create secret generic gitea-reports-publish-token \
+    --from-literal=token="$REPORTS_PUBLISH_TOKEN" \
+    -n "$NS"
+
+  # 3. Päivitä Gitea Actions secret jokaisessa repoissa (luke README:stä)
+  ```
+
+## Automatisointi: useamman repon salaisuuden lisääminen
+
+Jos repoja on monta, voit käyttää Gitea API:ta (vaatii admin-tokenin):
+
+```bash
+ADMIN_TOKEN="<gitea-admin-token>"
+NS=gitea-reports
+
+# Lue plaintext-token erillisestä secretistä
+TOKEN=$(kubectl get secret gitea-reports-publish-token -n "$NS" -o jsonpath='{.data.token}' | base64 -d)
+
+for repo in "owner/repo1" "owner/repo2" "owner/repo3"; do
+  curl -X POST "https://gitea.example.com/api/v1/repos/$repo/actions/secrets" \
+    -H "Authorization: token $ADMIN_TOKEN" \
+    -H "Content-Type: application/json" \
+    -d "{\"name\":\"REPORTS_PUBLISH_TOKEN\",\"data\":\"$TOKEN\"}"
+done
+```
+
+Tai `tea` CLI:lla (Gitea:n virallinen CLI):
+
+```bash
+tea actions secrets add --repo owner/repo1 REPORTS_PUBLISH_TOKEN "$TOKEN"
+tea actions secrets add --repo owner/repo2 REPORTS_PUBLISH_TOKEN "$TOKEN"
+```