Deployment

The Vol Dashboard deploys to Google Cloud Run only. Do not deploy this project to Vercel or any non-GCP target.

Canonical Production URLs

Cloud Run may also report *.a.run.app status URLs. Treat those as Cloud Run internal output only. Use the project-number canonical URLs in docs, tickets, and handoff notes.

The intended browser-facing UAT domain is https://uat-vol.bitwiseinvestments.dev. It is mapped directly to the Cloud Run frontend with automatic certificate provisioning once the bitwiseinvestments.dev domain owner creates the Cloud Run domain mapping and applies the returned DNS record.

Standard Deploy Command

Run from repository root:

./scripts/deploy-cloud-run.sh

This is the standard deployment path. It builds and deploys backend and frontend images, then prints the required evidence block.

Required Deploy Output

Every deploy handoff must include these lines from the script output:

Deployment complete:
Backend revision: vol-backend-<revision>
Frontend revision: vol-frontend-<revision>
Backend URL (canonical): https://vol-backend-244916812493.us-east4.run.app
Frontend URL (canonical): https://vol-frontend-244916812493.us-east4.run.app
Backend URL (Cloud Run status.url): https://vol-backend-<hash>-<region>.a.run.app
Frontend URL (Cloud Run status.url): https://vol-frontend-<hash>-<region>.a.run.app
Backend health check: HTTP 200
Frontend health check: HTTP 200

Do not move deployment work to review without backend and frontend health checks showing HTTP 200.

GCP Configuration

Secret References

Secrets are mounted as Cloud Run secret references. Do not pass secrets with --set-env-vars.

Non-Secret Environment Variables

Backend:

Frontend:

Manual Health Checks

Backend:

curl -s -o /dev/null -w '%{http_code}\n' \
  https://vol-backend-244916812493.us-east4.run.app/api/health

Frontend:

curl -s -o /dev/null -w '%{http_code}\n' \
  https://vol-frontend-244916812493.us-east4.run.app/

Expected output for both:

200

Manual Backend Deploy Reference

Use the standard script unless there is a specific reason to deploy manually.

./scripts/deploy-cloud-run.sh

Manual backend deploys must preserve the Cloud SQL annotation, secret references, CORS origins, Scheduler audience, service account, and Alpha feed env vars. Prefer updating the standard script rather than hand-running partial gcloud run services update commands.

When adding new secrets, use --update-secrets, not --set-secrets:

gcloud run services update vol-backend \
  --region us-east4 \
  --update-secrets=NEW_VAR=secret-name:latest

Manual Frontend Deploy Reference

The frontend bakes NEXT_PUBLIC_API_URL at build time, so changing the backend URL requires a rebuild.

cd front-end
gcloud builds submit --config=cloudbuild.yaml \
  --substitutions=_API_URL=https://vol-backend-244916812493.us-east4.run.app,_IMAGE=gcr.io/gen-lang-client-0466274674/vol-frontend \
  --region=us-east4

gcloud run deploy vol-frontend \
  --image gcr.io/gen-lang-client-0466274674/vol-frontend \
  --region us-east4 \
  --platform managed \
  --allow-unauthenticated

Cloud Scheduler

Daily snapshots are scheduled through Cloud Scheduler.

Never-Do List

• Never deploy this project to Vercel.
• Never use Vercel preview URLs for validation or handoff.
• Never use --set-secrets; it replaces all secret references. Use --update-secrets.
• Never pass API keys or admin secrets via --set-env-vars.
• Never hand off a deployment without backend/frontend revision names and health check codes.
• Never document *.a.run.app URLs as canonical URLs.
• Never change NEXT_PUBLIC_API_URL without rebuilding the frontend.
• Never cut over Cloud SQL without a verified backup/export and a documented rollback path.