# 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