CASAN/.gitea/okr-deploy-runbook.md

# OKR Web App — Deploy Runbook
# Oracle Cloud VPS: 161.33.139.73

## What this deploys

| Container     | Image              | Port         | Notes                          |
|---------------|--------------------|--------------|--------------------------------|
| okr-frontend  | nginx:alpine       | **80** (public)  | React SPA, proxies /api/v1/* → backend |
| okr-backend   | node:22-slim       | 3001 (internal) | NestJS + Prisma + SQLite       |

Network: `okr-net` (bridge, separate from Gitea/Vault)
Volume:  `okr-db` → mounted at `/data/okr.db` inside backend

---

## Step 1 — Add JWT_SECRET to Gitea Secrets

1. Open http://161.33.139.73:3000 → your repo → **Settings → Secrets → Actions**
2. Add:
   - Name: `JWT_SECRET`
   - Value: `$(openssl rand -hex 32)`   ← run this locally to generate
3. Save.

---

## Step 2 — Update act_runner config (Docker socket passthrough)

The deploy job needs Docker CLI inside the job container to build and run images.
The updated `act-runner-config.yaml` already includes:

```yaml
container:
  options: "--memory 512m --cpus 1.5 -v /var/run/docker.sock:/var/run/docker.sock"
```

Apply the new config on the VPS:

```bash
# Copy updated config
scp .gitea/act-runner-config.yaml ubuntu@161.33.139.73:/opt/gitea/act-runner-config.yaml

# Restart act_runner to pick up the new config
ssh ubuntu@161.33.139.73 "cd /opt/gitea && docker compose restart act-runner"
```

> The `-v /var/run/docker.sock:...` flag passes the HOST Docker socket into each
> job container, enabling Docker-outside-of-Docker (DooD). The socket is already
> in `valid_volumes: ["**"]` so no extra ACL change is needed.

---

## Step 3 — Push to main to trigger CI + deploy

```bash
git add Dockerfile.backend Dockerfile.frontend nginx/ backend/entrypoint.sh \
        .dockerignore .gitea/
git commit -m "feat: deploy OKR app to port 80/3001 via CI"
git push gitea main
```

Watch the pipeline: http://161.33.139.73:3000/<USER>/casan5/actions

Expected jobs:
1. **Frontend Tests** — 16 Vitest tests (~1 min)
2. **CASAN Security Gate** — harness + Vault signing (~3 min)
3. **Deploy OKR** — builds images + deploys (~5 min first time, ~2 min cached)

After deploy:
- **App**: http://161.33.139.73  (login: `admin@okr.local` / `Password@123`)
- **Gitea**: http://161.33.139.73:3000 (unchanged)

---

## Manual deploy (without CI)

If you need to deploy manually from the VPS:

```bash
ssh ubuntu@161.33.139.73

# Clone or pull repo
cd /opt/okr-app   # or wherever you checked out the repo

# Build images
docker build -t okr-backend:latest  -f Dockerfile.backend .
docker build \
  --build-arg VITE_API_BASE_URL=/api/v1 \
  -t okr-frontend:latest \
  -f Dockerfile.frontend .

# Network + volume
docker network create okr-net 2>/dev/null || true
docker volume create okr-db   2>/dev/null || true

# Backend
docker rm -f okr-backend 2>/dev/null || true
docker run -d \
  --name okr-backend \
  --network okr-net \
  -e PORT=3001 \
  -e DATABASE_URL=file:/data/okr.db \
  -e JWT_SECRET="$(openssl rand -hex 32)" \
  -e FRONTEND_ORIGIN="http://161.33.139.73" \
  -e NODE_ENV=production \
  -v okr-db:/data \
  --restart unless-stopped \
  okr-backend:latest

# Frontend (nginx)
docker rm -f okr-frontend 2>/dev/null || true
docker run -d \
  --name okr-frontend \
  --network okr-net \
  -p 80:80 \
  --restart unless-stopped \
  okr-frontend:latest

# Check
sleep 15
curl -sf http://localhost/ | grep -c "html" && echo "FRONTEND_UP"
docker logs okr-backend --tail 10
```

---

## RAM budget (1 GB VPS)

| Service        | Idle RAM  |
|----------------|-----------|
| Gitea          | ~180 MB   |
| act_runner     | ~50 MB    |
| Vault          | ~60 MB    |
| okr-backend    | ~120 MB   |
| okr-frontend   | ~25 MB    |
| **Total idle** | **~435 MB** ✅ |
| During CI build (Docker build on HOST) | +400 MB peak → ~835 MB ✅ |

---

## Troubleshooting

```bash
# Container status
docker ps -a | grep okr

# Backend logs (shows DB init + startup)
docker logs okr-backend --tail 50

# Frontend logs
docker logs okr-frontend --tail 20

# Re-seed database (drops + recreates)
docker exec okr-backend sh -c "rm /data/okr.db && kill 1"
# container restarts → auto re-initialises

# Check nginx proxy config
docker exec okr-frontend nginx -t
```