168 lines
5.6 KiB
Markdown
168 lines
5.6 KiB
Markdown
# OPAX Live Deployment Runbook
|
|
|
|
## Purpose
|
|
|
|
Use these scripts to deploy the two production components required for the
|
|
Emma/OPAX experience:
|
|
|
|
- OPAX MCP: the conversational MCP backend and `run_emma` tool service.
|
|
- OPAX Web: the live web application served at `https://opax.vauco.no`.
|
|
|
|
## Fixed Production Targets
|
|
|
|
| Item | Value |
|
|
|---|---|
|
|
| Google Cloud project | `propane-will-491900-m5` |
|
|
| Region | `us-central1` |
|
|
| Artifact Registry repository | `us-central1-docker.pkg.dev/propane-will-491900-m5/osvauco-repo` |
|
|
| MCP Cloud Run service | `opax-mcp` |
|
|
| OPAX Web Cloud Run service | `opax-web` |
|
|
| Live operator URL | `https://opax.vauco.no` |
|
|
|
|
## Normal Release Sequence
|
|
|
|
Run commands from the repository root:
|
|
|
|
```bash
|
|
./scripts/deploy-mcp.sh
|
|
./scripts/deploy-opax-web.sh
|
|
./scripts/check-live-services.sh
|
|
```
|
|
|
|
The scripts build an image, resolve its immutable digest, and deploy that digest
|
|
to the existing Cloud Run service.
|
|
|
|
## MCP Deployment Behavior
|
|
|
|
The existing `cloudbuild.deploy.yaml` workflow builds and pushes an MCP image.
|
|
Its internal Cloud Build deploy step can fail because the Cloud Build service
|
|
account is blocked by VPC Service Controls.
|
|
|
|
`deploy-mcp.sh` handles that condition by resolving the image that was pushed
|
|
during the build and then deploying its immutable digest directly through the
|
|
authenticated local `gcloud` session.
|
|
|
|
A Cloud Build failure does not automatically mean the image build failed. The
|
|
script stops if it cannot resolve an immutable pushed image digest.
|
|
|
|
## Live Validation
|
|
|
|
After deployment:
|
|
|
|
1. Open `https://opax.vauco.no`.
|
|
2. Hard-refresh the browser with `Ctrl+Shift+R`.
|
|
3. Log in normally.
|
|
4. Confirm that the new Emma workspace UI is visible.
|
|
5. In a new conversation, send:
|
|
|
|
```text
|
|
Jeg heter Chris.
|
|
```
|
|
|
|
6. In the same conversation, send:
|
|
|
|
```text
|
|
Hva heter jeg?
|
|
```
|
|
|
|
7. Confirm that Emma uses the previous message as conversation history.
|
|
8. Start a second conversation and ask:
|
|
|
|
```text
|
|
Hva heter jeg?
|
|
```
|
|
|
|
9. Confirm that the second conversation does not inherit context from the first
|
|
conversation.
|
|
|
|
## Guardrails
|
|
|
|
- Use `us-central1` only.
|
|
- Never deploy to `europe-west1`.
|
|
- Never deploy a service named `opax`.
|
|
- Deploy only the existing `opax-mcp` and `opax-web` services.
|
|
- Final Cloud Run deployment must use an immutable image digest.
|
|
- Never use a mutable tag for the final deploy.
|
|
- Never print or place secret values in scripts, logs, documentation, or Git.
|
|
- Do not deploy from Gemini without explicit human approval.
|
|
- Do not change IAM, service accounts, secrets, VPC settings, DNS, OAuth, or
|
|
Cloud Run networking as part of a normal application release.
|
|
|
|
## Rollback
|
|
|
|
Use one of these existing rollback methods:
|
|
|
|
1. In Cloud Run, route traffic back to the prior ready revision.
|
|
2. Re-run the relevant deployment script after replacing the image digest with a
|
|
previously known good immutable digest.
|
|
|
|
Use `./scripts/check-live-services.sh` to record the currently active revisions
|
|
and images before a release.
|
|
|
|
---
|
|
|
|
## Appendix: `git-update.sh` Script
|
|
|
|
### Hensikt og sikkerhetsmodell
|
|
|
|
`scripts/git-update.sh` er en sikker wrapper for git-operasjoner mot prosjektets Gitea-repository, designet for å forhindre vanlige feil og håndheve beste praksis for versjonskontroll.
|
|
|
|
### Kommandoer
|
|
|
|
Scriptet bruker et subkommando-grensesnitt:
|
|
|
|
#### **`./scripts/git-update.sh status`**
|
|
|
|
Viser status for repositoryet. Dette er standardvalget hvis ingen subkommando gis.
|
|
|
|
#### **`./scripts/git-update.sh commit [--allow-main] -m "<melding>" -- <fil1> [...]`**
|
|
|
|
Stager en eksplisitt liste filer, validerer, og kjører deretter en interaktiv `commit` og `push` i én operasjon.
|
|
|
|
- **`--allow-main`**: Valgfritt flagg som må brukes for å commite direkte til `main`-branchen.
|
|
- **`-m "<melding>"`**: En obligatorisk commit-melding.
|
|
- **`-- <filer>`**: En eller flere filer som skal behandles.
|
|
|
|
#### **`./scripts/git-update.sh push [--allow-main]`**
|
|
|
|
Pusher en *allerede opprettet* lokal commit som ennå ikke er lastet opp til Gitea.
|
|
|
|
### Sikkerhetsgarantier
|
|
|
|
1. **Gitea-validering**: Scriptet verifiserer at `origin` peker til prosjektets godkjente Gitea-repository. Det vil nekte å kjøre hvis `origin` er GitHub eller en ukjent URL.
|
|
2. **Ingen Pre-staged Commits**: Scriptet avbryter hvis det finnes filer i "staging area" *før* `git add`-kommandoen kjøres. Dette forhindrer at utilsiktede endringer blir med i en commit.
|
|
3. **Eksplisitt filliste**: Kun filene som listes eksplisitt etter `--` blir lagt til i staging. Scriptet bruker aldri `git add .` eller `git add -A`.
|
|
4. **Whitespace-sjekker**: Før og etter staging kjøres `git diff --check` for å avdekke og stoppe ved whitespace-feil.
|
|
5. **Interaktiv bekreftelse**: Før en commit og push, vises en status over stagede filer, og brukeren må bekrefte med `y`. Hvis brukeren avbryter, forblir de eksplisitt stagede filene i staging area, men ingen commit eller push utføres.
|
|
6. **Beskyttelse av `main`**: Operasjoner (commit/push) mot `main`-branchen er blokkert med mindre det eksplisitte `--allow-main` flagget er brukt.
|
|
7. **Trygg Push**: Bruker `git push origin <current_branch>`. Bruker aldri `git push --force`.
|
|
|
|
### Eksempler
|
|
|
|
**Sjekk status:**
|
|
|
|
```bash
|
|
./scripts/git-update.sh status
|
|
```
|
|
|
|
**Commit og push til en feature-branch:**
|
|
|
|
```bash
|
|
./scripts/git-update.sh commit -m "feat: Add new script" -- \
|
|
scripts/new-script.sh \
|
|
docs/new-doc.md
|
|
```
|
|
|
|
**Push en allerede opprettet commit:**
|
|
|
|
```bash
|
|
./scripts/git-update.sh push
|
|
```
|
|
|
|
**Avbrudd på grunn av pre-stagede endringer:**
|
|
|
|
```text
|
|
FEIL: Repositoryet har allerede staged endringer.
|
|
Avbryter for å hindre at filer utenfor den eksplisitte fillisten blir committet.
|
|
Kjør: git diff --cached --name-status
|
|
``` |