docs(runner): add runtime environment documentation and fix Helm guide

Fix chart values (enabled, giteaRootURL, existingSecret), add log level
config, and document runner architecture: containers, services, DinD,
labels, and Jenkins comparison.

README.md

@@ -12,8 +12,6 @@ Hae token Giteasta:
 - **Organization-taso:** Org → Settings → Actions → Runners → Create new runner
 - **Globaali (site admin):** Site Admin → Actions → Runners → Create new runner
 
-Token on kertakäyttöinen — käytä heti.
-
 ### 2. Asenna runner
 
 ```bash
@@ -23,26 +21,53 @@ GITEA_ACTIONS_NAMESPACE="gitea-actions"
 
 helm repo add gitea https://dl.gitea.com/charts
 helm repo update
-helm upgrade --install act-runner gitea/gitea-act-runner \
-  --set gitea.url="$GITEA_URL" \
-  --set gitea.token="$GITEA_ACTIONS_TOKEN" \
+
+kubectl create secret generic act-runner-token \
+  --from-literal=token="$GITEA_ACTIONS_TOKEN" \
+  --namespace "$GITEA_ACTIONS_NAMESPACE" \
+  --dry-run=client -o yaml | kubectl apply -f -
+
+helm upgrade --install act-runner gitea/actions \
+  --set enabled=true \
+  --set giteaRootURL="$GITEA_URL" \
+  --set existingSecret=act-runner-token \
+  --set existingSecretKey=token \
+  --set-string 'statefulset.runner.config=log:
+  level: info
+cache:
+  enabled: false
+container:
+  require_docker: true
+  docker_timeout: 300s' \
   --namespace "$GITEA_ACTIONS_NAMESPACE" \
   --create-namespace
 ```
 
+Oletus-lokitaso on `debug` — suositeltu `info`. Näkee jobien aloitukset ja valmistumiset ilman konttikerrosten purkua (Downloading/Extracting-spämmiä). `debug` on tarpeen vain vianselvityksessä.
+
 ### 3. Varmista
 
 ```bash
 kubectl get pods -n gitea-actions
-# → act-runner-xxx  Running
+# → act-runner-runner-0  2/2  Running
+```
+
+Gitean puolella runner ilmestyy Active-tilaan pienellä viiveellä:
+
+```
+Site Admin → Actions → Runners  (tai Org → Settings → Actions → Runners)
+# → act-runner-runner-0  Active  ubuntu-latest
 ```
 
 Tämän jälkeen `.gitea/workflows/ci.yml` triggeröityy automaattisesti pushista.
 
+Lisätietoa runnerin toiminnasta, konteista ja DinD:stä: [docs/runner.md](docs/runner.md)
+
 ### Muuta
 
 | Muuttuja | Kuvaus |
 |----------|--------|
-| `gitea.url` | Gitea-palvelimen osoite (esim. `https://gitea.example.com`) |
-| `gitea.token` | Rekisteröintitoken (kts. kohta 1) |
-| `runner.labels` | Mukautetut labelit (oletus: `ubuntu-latest`) |
+| `giteaRootURL` | Gitea-palvelimen osoite (esim. `https://gitea.example.com`) |
+| `existingSecret` | Kubernetes secretin nimi, jossa token |
+| `existingSecretKey` | Avain secretin sisällä |
+| `statefulset.runner.labels` | Mukautetut labelit |

docs/architecture.md

@@ -54,6 +54,7 @@ Kirjasto on Gitea-spesifi. Se hyödyntää Gitean REST API:a commit-statusraport
 |---------|-------|
 | **Gitea REST API** | Commit-statusraportointi, workflow-dispatch, run-pollaus, taggaus |
 | **Gitea Packages** | Docker-imagen ja NPM-paketin säilytys |
+| **Gitea act runner** | Suorittaa workflowt. Konteista, DinD:stä ja label-järjestelmästä: [runner.md](runner.md) |
 | **MinIO** | Testiraporttien tallennus ja staattinen web-hosting |
 | **SonarQube** | Koodin laadun analyysi ja quality gate |
 

docs/runner.md

@@ -0,0 +1,111 @@
+# Gitea Actions — Runtime-ympäristö
+
+> Kuuluu arkkitehtuuriin: [architecture.md](architecture.md). Asennusohjeet: [README.md](../README.md).
+>
+> Tämä dokumentti kuvaa miten Gitea Actions runner suorittaa workflowt ja minkälaisen runtime-ympäristön se tarjoaa.
+
+---
+
+## Runnerin rooli
+
+Runner on **pelkkä suoritin**. Se ei sisällä build-työkaluja (Maven, npm, Docker) — ne tulevat workflow'n määrittelemistä konteista. Runner vastaanottaa työt Gitea-palvelimelta, ajaa ne ja raportoi tulokset takaisin.
+
+```
+Gitea → dispatch job → Runner → pull containers → execute steps → report status
+```
+
+Runnerilla on yksi vastuu: **suorittaa workflow-steppejä**. Kaikki runtime-ympäristön määrittely tapahtuu workflow-tiedostossa.
+
+## Kontit ja palvelut
+
+Jokainen job voi määritellä käyttämänsä kontit. Tämä vastaa Jenkinsin pod template -konseptia, mutta on yksinkertaisempi:
+
+### `container:` — ajonaikainen ympäristö
+
+Workflow-steppi ajetaan tässä kontissa. Eri jobeilla voi olla eri kontti:
+
+```yaml
+jobs:
+  build-java:
+    runs-on: ubuntu-latest
+    container: maven:3.9-eclipse-temurin-21
+    steps:
+      - run: mvn verify
+
+  build-node:
+    runs-on: ubuntu-latest
+    container: node:22
+    steps:
+      - run: npm ci && npm test
+```
+
+### `services:` — rinnakkaiset palvelut
+
+Palvelukontit käynnistyvät jobin ajaksi ja ovat käytettävissä `localhost`-verkon kautta:
+
+```yaml
+jobs:
+  build-with-docker:
+    runs-on: ubuntu-latest
+    container: maven:3.9-eclipse-temurin-21
+    services:
+      docker:
+        image: docker:dind
+        env:
+          DOCKER_TLS_CERTDIR: ""
+    steps:
+      - run: mvn package
+      - run: docker build -t my-app .
+```
+
+Kontit vedetään ajonaikaisesti registrystä (Docker Hub, Gitea Packages, mikä tahansa). Runnerin ei tarvitse tietää niistä etukäteen.
+
+### Docker-in-Docker
+
+Runner-podilla on kaksi tapaa käyttää Dockeria:
+
+| Tapa | Kuvaus | Sopii |
+|------|--------|-------|
+| **DinD** (`docker:dind`) | Oma Docker daemon service-kontissa | Suositeltu K8s-ympäristöön |
+| **Docker socket** | Jaettu `/var/run/docker.sock` | Yksinkertainen, vähemmän eristetty |
+
+Gitea act runnerin Helm chart tukee DinD:tä oletuksena.
+
+## Label-järjestelmä
+
+Runnerit rekisteröidään labelilla. Workflow valitsee runnerin `runs-on`-kentällä:
+
+```yaml
+jobs:
+  build:
+    runs-on: ubuntu-latest    # ← label
+```
+
+Labelit asetetaan runnerin rekisteröinnissä:
+
+```bash
+# Helm
+--set runner.labels="ubuntu-latest,docker,arm64"
+
+# Binääri
+./act_runner register --labels ubuntu-latest,docker
+```
+
+Eri labelit mahdollistavat erikoistuneet runnerit (ARM, GPU, Windows), mutta MVP:ssä riittää yksi `ubuntu-latest`.
+
+## Runner-tasot
+
+| Taso | Scope | Riski | Käyttötapaus |
+|------|-------|-------|--------------|
+| **Global** | Kaikki organisaatiot ja repot | Token-vuoto → hyökkääjä voi ajaa koodia missä tahansa | Jaettu infra, keskitetty hallinta |
+| **Organization** | Yhden organisaation repot | Rajoittuu yhteen orgiin | Per organisaatio, eristetty — **suositeltu** |
+
+## Jenkins-vertailu
+
+| Jenkins | Gitea Actions |
+|---------|--------------|
+| Pod template (YAML) määrittelee kontit | `container:` + `services:` per job |
+| Jokaiselle jobille oma pod | Jokaiselle jobille omat konttimääritykset |
+| DinD sidecar-podissa | `services: docker:dind` samassa jobissa |
+| Agentti = erillinen JVM-prosessi | Runner = kevyt Go-binääri tai K8s-pod |
+| Labelit Jenkins-nodessa | Labelit runner-rekisteröinnissä |