OSVauco/docs/RUNBOOK-deploy.md

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

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

git log --oneline -10
# Finn siste grønne build i Cloud Build console

Steg 2 — Se hva som faktisk endret seg

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

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:

  git revert HEAD
  git push
  

• Smoke-test 404 = modulproblem, ikke nettverksproblem — ikke øk retry-antall, finn rotårsaken