From f549ba9a5792c06b34e3106b3510a36b7ca44319 Mon Sep 17 00:00:00 2001
From: chrischristiansen-glitch <chris.christiansen@vauco.no>
Date: Wed, 10 Jun 2026 10:33:51 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20legg=20til=20RUNBOOK-deploy.md=20med=20?=
 =?UTF-8?q?l=C3=A6rdom=20fra=20CI-6=20deploy-krise?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/RUNBOOK-deploy.md | 76 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 docs/RUNBOOK-deploy.md

diff --git a/docs/RUNBOOK-deploy.md b/docs/RUNBOOK-deploy.md
new file mode 100644
index 0000000..e9ad943
--- /dev/null
+++ b/docs/RUNBOOK-deploy.md
@@ -0,0 +1,76 @@
+# RUNBOOK: OSVauco Deploy — Lærdom fra CI-6 (2026-06-10)
+
+> **Til Jason og Emma** — les dette før du endrer noe i Dockerfile, cloudbuild.yaml eller app.py.
+
+---
+
+## 🔴 Hva gikk galt i dag
+
+En fungerende deploy (`6981359`, kl 07:55) ble ødelagt av en kjede av feil:
+
+1. **Aldri generer filer med `printf` i Dockerfile.** `RUN printf '...' > main.py` produserer korrupte filer med feil encoding/linjeskift. Bruk alltid en ekte fil i repoet.
+2. **Ikke endre Dockerfile uten å forstå hva som var riktig.** Den fungerende builden hadde `uvicorn main:app` med `WORKDIR /app/agents/core-logic`. Det var korrekt.
+3. **HTTP 404 fra smoke-test ≠ container nede.** 404 betyr containeren kjører men ruter ikke eksisteres — sjekk `main:app` modulnavn og WORKDIR.
+4. **Ikke fikse ting som ikke er ødelagt.** Analyser *hvilken commit* som brøt noe og *hva* som endret seg — ikke start med å endre Dockerfile på måfå.
+
+---
+
+## ✅ Korrekt Dockerfile-struktur
+
+```dockerfile
+FROM .../osvauco-base:latest
+WORKDIR /app/agents/core-logic      # <- uvicorn finner main.py her
+COPY agents/core-logic/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+ENV PYTHONPATH=/app:/app/agents/core-logic
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]
+```
+
+- `main.py` ligger i `agents/core-logic/main.py` som en **ekte fil i repoet**
+- `main.py` gjør kun: `from app import app`
+- `agents/__init__.py` må eksistere for at `from agents.recommendations_engine import ...` skal fungere
+
+---
+
+## 🔍 Feilsøkingsprotokoll ved deploy-feil
+
+### Steg 1 — Finn siste fungerende commit
+```bash
+git log --oneline -10
+# Finn siste grønne build i Cloud Build console
+```
+
+### Steg 2 — Se hva som faktisk endret seg
+```bash
+git diff <fungerende-sha> <feilende-sha> -- agents/core-logic/Dockerfile
+git diff <fungerende-sha> <feilende-sha> -- cloudbuild.yaml
+```
+
+### Steg 3 — Tolke smoke-test feilmeldinger
+
+| Feilmelding | Betydning | Løsning |
+|---|---|---|
+| `HTTP 404` | Container oppe, feil modul/rute | Sjekk `CMD` i Dockerfile og `main:app` |
+| `HTTP 500` | Container oppe, Python-feil ved oppstart | Se Cloud Run logs |
+| `Connection refused` | Container starter ikke | Se Cloud Run logs for ImportError/crash |
+| `Could not fetch token` | IAM/impersonation-feil | Sjekk service account permissions |
+
+### Steg 4 — Se Cloud Run logs direkte
+```bash
+gcloud logging read 'resource.type=cloud_run_revision AND resource.labels.service_name=osvauco-agent' \
+  --limit=50 --project=propane-will-491900-m5 --format='value(textPayload)'
+```
+
+---
+
+## ⚠️ Regler for endringer i produksjon
+
+- **Aldri push direkte til `main` uten å teste lokalt først** hvis du endrer Dockerfile eller app.py
+- **Sjekk alltid Cloud Run logs** — ikke bare Cloud Build logs — når noe feiler etter deploy
+- **Revert er raskere enn å fikse fremover** når du ikke vet hva som er galt:
+  ```bash
+  git revert HEAD
+  git push
+  ```
+- **Smoke-test 404 = modulproblem, ikke nettverksproblem** — ikke øk retry-antall, finn rotårsaken