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:

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

Apply the new config on the VPS:

# 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

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//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:

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

# 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