Bookra/docs/ci-cd.md

Bookra CI/CD

Current shape

• CI runs in GitHub Actions from .github/workflows/ci.yml.
• Frontend CD should stay on Vercel Git deployments.
• Backend and auth-service can stay on Railway Git autodeploys, or consume GHCR images built by CI.

This keeps Vercel/Railway Git deployment simple while still producing immutable backend images on every production push.

CI coverage

Every pull request, push to main, and manual workflow run executes:

1. frontend install, API client generation, typecheck, and production build
2. backend go test + go build
3. auth-service go test + go build
4. Docker image builds for apps/backend and apps/auth-service
5. GHCR publishing on push to main and manual workflow runs

Go is pinned to 1.26.2, the latest stable release at time of setup.

Platform CD wiring

Vercel

• Create Vercel project for frontend.
• Set project root directory to apps/frontend.
• Keep Git-based deployments enabled for main.
• Let Vercel keep monorepo auto-detection enabled. Vercel documents monorepo root-directory support and automatic per-project Git deployments.
• Only override build settings if auto-detection is wrong during first import.

Railway

Create two Railway services from this repo:

• backend root directory: apps/backend
• auth-service root directory: apps/auth-service

Both services now have code-based Railway config:

• apps/backend/railway.json
• apps/auth-service/railway.json

Enable for each service:

• GitHub Autodeploys
• Wait for CI

Health checks:

• backend: /healthz
• auth-service: /health

Published images:

• ghcr.io/<owner>/bookra-backend:<sha|branch|latest>
• ghcr.io/<owner>/bookra-auth-service:<sha|branch|latest>

Use SHA tags for production rollouts. latest is emitted only from the default branch.

Local mirror of CI

PATH=/usr/local/go/bin:$PATH npm run verify
docker build -t bookra-backend-ci ./apps/backend
docker build -t bookra-auth-ci ./apps/auth-service

Low-RAM act checks

For local GitHub Actions validation on a memory-constrained machine, run one job at a time:

act push -W .github/workflows/ci.yml -j frontend \
  --concurrent-jobs 1 -b \
  --container-options='--memory=3g --cpus=2'

act push -W .github/workflows/ci.yml -j go \
  --matrix app:apps/backend \
  --concurrent-jobs 1 -b \
  --container-options='--memory=3g --cpus=2'

Notes:

• frontend job was executed successfully with act.
• go job was executed successfully with act for apps/backend.
• Dockerfiles were validated with direct docker build, which is cheaper than running full Docker-action matrix through act.