@slingr/cli 0.0.3 → 0.0.4

package/dist/templates/ops/README.md.template

@@ -0,0 +1,1045 @@
+# GCP Deployment Guide — Slingr Framework Apps
+
+A step-by-step guide for deploying **{{APP_NAME}}** (a Slingr framework app) to Google Cloud Platform.
+
+---
+
+## Table of Contents
+
+- [GCP Deployment Guide — Slingr Framework Apps](#gcp-deployment-guide--slingr-framework-apps)
+  - [Table of Contents](#table-of-contents)
+  - [Architecture Overview](#architecture-overview)
+  - [Prerequisites](#prerequisites)
+    - [Tools](#tools)
+    - [GCP Setup](#gcp-setup)
+    - [Required GCP IAM Permissions](#required-gcp-iam-permissions)
+  - [File Structure Convention](#file-structure-convention)
+  - [Script Execution Order](#script-execution-order)
+  - [Adapting the Scripts for Your App](#adapting-the-scripts-for-your-app)
+    - [Variable mapping](#variable-mapping)
+  - [Step 1 — Backend Dockerfile](#step-1--backend-dockerfile)
+    - [Build context](#build-context)
+  - [Step 2 — Local Production Smoke Testing](#step-2--local-production-smoke-testing)
+    - [Quick start](#quick-start)
+    - [Manual step-by-step](#manual-step-by-step)
+    - [What to verify](#what-to-verify)
+    - [Iterating quickly](#iterating-quickly)
+  - [Step 3 — One-Time GCP Infrastructure Setup](#step-3--one-time-gcp-infrastructure-setup)
+    - [What it creates](#what-it-creates)
+    - [After running](#after-running)
+  - [Step 4 — Secrets Management](#step-4--secrets-management)
+    - [Rotating secrets later](#rotating-secrets-later)
+  - [Step 5 — Cloud Build Trigger (Automated Deploys)](#step-5--cloud-build-trigger-automated-deploys)
+    - [Connect the GitHub repository (one-time)](#connect-the-github-repository-one-time)
+    - [Create the trigger](#create-the-trigger)
+    - [cloudbuild.yaml structure](#cloudbuildyaml-structure)
+  - [Step 6 — Manual Deployment](#step-6--manual-deployment)
+  - [Step 7 — DNS \& HTTPS Setup (Optional)](#step-7--dns--https-setup-optional)
+    - [What setup-domain.js does](#what-setup-domainjs-does)
+    - [After running setup-domain.js](#after-running-setup-domainjs)
+    - [Manual equivalent (no script)](#manual-equivalent-no-script)
+  - [Networking](#networking)
+    - [What was set up](#what-was-set-up)
+    - [Cloud SQL connectivity](#cloud-sql-connectivity)
+    - [Verifying the networking setup](#verifying-the-networking-setup)
+  - [Frontend Hosting](#frontend-hosting)
+    - [URL routing](#url-routing)
+    - [Manual frontend deploy](#manual-frontend-deploy)
+    - [CDN cache invalidation](#cdn-cache-invalidation)
+  - [Database Schema Sync](#database-schema-sync)
+  - [Default Admin User](#default-admin-user)
+  - [Logging \& Observability](#logging--observability)
+    - [View backend logs](#view-backend-logs)
+    - [Stream live logs](#stream-live-logs)
+    - [Useful log filters](#useful-log-filters)
+    - [Cloud Monitoring — uptime check](#cloud-monitoring--uptime-check)
+    - [Cloud Monitoring — error rate alert](#cloud-monitoring--error-rate-alert)
+  - [IAM \& Service Accounts Reference](#iam--service-accounts-reference)
+    - [Runtime service account (`<app>-backend`)](#runtime-service-account-app-backend)
+    - [Cloud Build service account (CI/CD)](#cloud-build-service-account-cicd)
+  - [Ongoing Operations](#ongoing-operations)
+    - [Roll back to a previous revision](#roll-back-to-a-previous-revision)
+    - [Scale to zero immediately](#scale-to-zero-immediately)
+    - [Connect to Cloud SQL from your local machine](#connect-to-cloud-sql-from-your-local-machine)
+  - [Troubleshooting](#troubleshooting)
+    - [Backend fails to connect to Cloud SQL](#backend-fails-to-connect-to-cloud-sql)
+    - [Cloud Run service fails to start](#cloud-run-service-fails-to-start)
+    - [Schema sync job exits non-zero](#schema-sync-job-exits-non-zero)
+    - [Docker build fails: `cannot find module '@slingr/framework-backend'`](#docker-build-fails-cannot-find-module-slingr-frameworkbackend)
+    - [Docker push fails: Unauthenticated request](#docker-push-fails-unauthenticated-request)
+    - [Cloud SQL Proxy is not recognized on local machine](#cloud-sql-proxy-is-not-recognized-on-local-machine)
+    - [Frontend not updating after deploy](#frontend-not-updating-after-deploy)
+    - [Load Balancer returns 404 for frontend routes](#load-balancer-returns-404-for-frontend-routes)
+    - [SSL certificate stuck in PROVISIONING](#ssl-certificate-stuck-in-provisioning)
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Users (browser)                         │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │ HTTP/HTTPS
+              ┌─────────────▼──────────────┐
+              │   Cloud HTTP(S) Load Balancer  │
+              │  /graphql → Cloud Run NEG   │
+              │  /auth/*  → Cloud Run NEG   │
+              │  /**      → GCS bucket CDN  │
+              └──────┬──────────────┬───────┘
+                     │              │
+       ┌─────────────▼──┐    ┌──────▼──────────────┐
+       │   Cloud Run     │    │  GCS Bucket (CDN)   │
+       │  <app>-backend  │    │  React SPA static   │
+       └────────┬────────┘    └─────────────────────┘
+                │ Cloud SQL Auth Proxy (IAM, encrypted)
+       ┌────────▼────────┐
+       │    Cloud SQL    │  PostgreSQL 15
+       │   <app>-db      │
+       └─────────────────┘
+
+Secrets  →  Secret Manager  (DB password, JWT secret)
+Images   →  Artifact Registry  (Docker)
+CI/CD    →  Cloud Build  (triggered on push to a branch)
+```
+
+**Why this architecture:**
+
+| Service | Choice | Reason |
+|---|---|---|
+| Backend | Cloud Run | Serverless, scales to zero, $0 when idle |
+| Frontend | GCS + Cloud LB | CDN-backed static hosting, no extra IAM roles |
+| Database | Cloud SQL (PostgreSQL 15) | Managed, automated backups, point-in-time recovery |
+| DB connectivity | Cloud SQL Auth Proxy | Native Cloud Run integration, no VPC connector needed |
+| Secrets | Secret Manager | Audit trail, rotation support, IAM-scoped access |
+
+---
+
+## Prerequisites
+
+### Tools
+
+| Tool | Min Version | Install | Purpose |
+|---|---|---|---|
+| **gcloud CLI** | >= 450.0.0 | [Install guide](https://cloud.google.com/sdk/docs/install) | GCP resource management |
+| **Docker** | >= 24.0 | [Install guide](https://docs.docker.com/get-docker/) | Build backend container image |
+| **Node.js** | >= 20.0 | [Install guide](https://nodejs.org/) | Build frontend, run CLI commands |
+| **pnpm** | >= 8.0 | `npm install -g pnpm` | Monorepo workspace dependency management |
+| **Cloud SQL Auth Proxy** | latest | `gcloud components install cloud-sql-proxy` | Local DB connection for seeding |
+| **gsutil** | bundled | Included in gcloud CLI | Upload frontend files to GCS |
+
+```bash
+# Verify all dependencies
+gcloud --version          # >= 450.0.0
+docker --version          # >= 24.0
+node --version            # >= 20.0
+pnpm --version            # >= 8.0
+cloud-sql-proxy --version
+gsutil --version
+```
+
+### GCP Setup
+
+- GCP project created with billing enabled
+- Required IAM roles on the project (see next section)
+- `gcloud init` — sets your authenticated account and default project on this machine
+- `gcloud auth application-default login` — sets Application Default Credentials for local SDK usage
+- `gcloud auth configure-docker REGION-docker.pkg.dev` — authenticates Docker to push images to Artifact Registry
+
+> **Important:** `setup-gcp.js` and `setup-secrets.js` are **project-level** bootstrap steps — run once per GCP project. `gcloud init`, `gcloud auth ...`, and installing the gcloud CLI are **machine-level** prerequisites. If you switch machines, install `gcloud` and authenticate again before running any scripts.
+
+If the project was already provisioned from another machine:
+
+```bash
+# 1. Install Google Cloud CLI on this machine
+# https://cloud.google.com/sdk/docs/install
+
+# 2. Authenticate this machine
+gcloud init
+gcloud auth application-default login
+
+# 3. Install Cloud SQL Auth Proxy
+gcloud components install cloud-sql-proxy
+cloud-sql-proxy --version
+
+# 4. Authenticate Docker to Artifact Registry
+gcloud auth configure-docker us-central1-docker.pkg.dev
+
+# 5. Deploy (run from your app root)
+node ops/scripts/deploy.js
+```
+
+### Required GCP IAM Permissions
+
+The human (or CI service account) running the setup and deployment scripts must have the following roles on the GCP project. The simplest option is `roles/owner`. For least-privilege setups, grant the specific roles:
+
+| Role | Required for |
+|---|---|
+| `roles/resourcemanager.projectIamAdmin` | Granting IAM bindings to service accounts in `setup-gcp.js` |
+| `roles/iam.serviceAccountAdmin` | Creating the backend service account |
+| `roles/compute.admin` | Creating the Load Balancer (NEG, URL map, forwarding rules, backend services) |
+| `roles/cloudsql.admin` | Creating the Cloud SQL instance, database, and setting user passwords |
+| `roles/artifactregistry.admin` | Creating the Artifact Registry repository |
+| `roles/run.admin` | Deploying Cloud Run services and jobs |
+| `roles/secretmanager.admin` | Creating and versioning secrets in Secret Manager |
+| `roles/storage.admin` | Creating and configuring the GCS bucket |
+| `roles/serviceusage.serviceUsageAdmin` | Enabling GCP APIs |
+| `roles/cloudbuild.builds.editor` | Creating Cloud Build triggers |
+
+---
+
+## File Structure Convention
+
+Each app should have an `ops/` directory mirroring this layout:
+
+```
+apps/<your-app>/
+├── backend/
+│   └── Dockerfile                     # Multi-stage build (see Step 1)
+├── frontend/
+│   └── src/services/GraphQLClientService.ts
+└── ops/
+    ├── README.md                      # This guide
+    ├── cloudbuild.yaml                # Cloud Build CI/CD pipeline
+    ├── nginx/
+    │   └── prod-test.conf             # nginx config for local smoke testing
+    └── scripts/
+        ├── setup-gcp.js               # One-time infrastructure setup
+        ├── setup-secrets.js           # Secret Manager credential management
+        ├── setup-domain.js            # Custom domain + HTTPS setup (optional)
+        ├── deploy.js                  # Manual deployment script
+        └── test-prod-local.js         # Local production smoke test
+```
+
+The scripts in `ops/scripts/` have been pre-configured for **{{APP_NAME}}**. No manual variable substitution is needed.
+
+---
+
+## Script Execution Order
+
+The scripts are designed to be run in this order. Each step builds on the previous one.
+
+```
+1. (dockerfile)          Step 1: Backend Dockerfile — copy and adapt the Dockerfile
+2. test-prod-local.js    Step 2: Verify the full production stack runs correctly in Docker locally
+3. setup-gcp.js          Step 3: Create all GCP infrastructure (run once per project)
+4. setup-secrets.js      Step 4: Store DB password and JWT secret in Secret Manager
+5. (trigger creation)    Step 5: Create the Cloud Build trigger for automated deploys
+6. deploy.js             Step 6: First manual deployment to GCP
+7. setup-domain.js       Step 7: (Optional) Add a custom domain and HTTPS
+```
+
+> **`setup-domain.js` is optional and can be run any time after `setup-gcp.js`** — It requires that the Load Balancer already exists (created by `setup-gcp.js`) but is otherwise independent of deployment state.
+
+> **You do not need a domain to deploy.** Without `setup-domain.js`, the app is accessible over HTTP on the Load Balancer IP that `setup-gcp.js` prints at the end. HTTPS with a custom domain is an optional step for production environments.
+
+---
+
+## GCP Resource Naming Reference
+
+The scripts use `{{APP_NAME}}` as the base identifier for all GCP resource names. Here is the full mapping for reference:
+
+### Variable mapping
+
+| Variable | Description | Value for {{APP_NAME}} |
+|---|---|---|
+| `APP_SHORT` | Short identifier used as a prefix for every GCP resource name. Keep it lowercase, hyphen-separated, and unique within the project. | `<your-app-short>` |
+| `DB_INSTANCE_NAME` | Name of the Cloud SQL instance. One instance can host multiple databases. | `{{APP_NAME}}-db` |
+| `DB_NAME` | Database name. PostgreSQL database inside the instance. Used as `DB_NAME` env var at runtime. | `{{APP_NAME}}` |
+| `DB_USER` | PostgreSQL user the backend connects as. | `postgres` | superuser is used for simplicity |
+| `AR_REPO_NAME` | Shared Docker registry across all apps in the project. | `slingr-apps` || `APP_SHORT` | Short identifier used as a prefix for every GCP resource name. Keep it lowercase, hyphen-separated, and unique within the project. | `<your-app-short>` |
+| `BACKEND_SA_NAME` | Backend service account | Runtime identity for Cloud Run. Granted minimum roles. | `{{APP_NAME}}-backend` |
+| `BACKEND_SERVICE` | Cloud Run service | The deployed backend service. Also used as the Docker image name. | `{{APP_NAME}}-backend` |
+| `FRONTEND_BUCKET` | GCS bucket | Hosts the React SPA static files. Globally unique. | `PROJECT_ID-{{APP_NAME}}-frontend` |
+| `NEG_NAME` | Serverless NEG | Connects the Load Balancer to Cloud Run. | `{{APP_NAME}}-backend-neg` |
+| `URL_MAP_NAME` | Path-based routing (`/graphql` → Cloud Run, `/**` → GCS). | `{{APP_NAME}}-url-map` |
+| `HTTP_PROXY_NAME` | Routes HTTP requests into the URL map. | `{{APP_NAME}}-http-proxy` |
+| `FWD_RULE_NAME` | Port 80, assigns public IP. | `{{APP_NAME}}-http-rule` |
+| `DB_SECRET_NAME` | Cloud SQL `postgres` password in Secret Manager. | `{{APP_NAME}}-db-password` |
+| `JWT_SECRET_NAME` | JWT signing key in Secret Manager. | `{{APP_NAME}}-jwt-secret` |
+
+
+---
+
+## Step 1 — Backend Dockerfile
+
+The `backend/Dockerfile` has been generated for your app. It uses a two-stage build:
+
+1. **Stage 1 (builder):** Installs dependencies (`npm install`), compiles TypeScript (`npm run build`).
+2. **Stage 2 (runtime):** Copies only `dist/` and `node_modules/`. Exposes port 8080. Starts with `node dist/src/App.js`.
+
+### Build context
+
+The build context is the **app root directory** (the folder containing `backend/` and `frontend/`):
+
+```bash
+# Run from your app root
+docker build \
+  -f backend/Dockerfile \
+  -t REGION-docker.pkg.dev/PROJECT_ID/slingr-apps/{{APP_NAME}}-backend:latest \
+  .
+```
+
+The Cloud Build pipeline and `deploy.js` enforce this automatically.
+
+---
+
+## Step 2 — Local Production Smoke Testing
+
+Before touching GCP, run the full production stack locally. This catches environment-specific bugs that only appear in production builds — minified bundles, URL routing, Docker runtime config — without creating any cloud resources.
+
+The local stack mirrors the GCP topology exactly:
+
+```
+Browser
+  └─► nginx :8080
+        ├─ /graphql  →  backend:3000  (Node.js container)
+        ├─ /auth/*   →  backend:3000
+        └─ /**       →  React SPA (frontend/dist/)
+              backend:3000
+                └─ mainDs-db:5432  (PostgreSQL 15)
+```
+
+### Quick start
+
+Run from the **app root** (the directory containing `backend/`, `frontend/`, and `ops/`):
+
+```bash
+node ops/scripts/test-prod-local.js
+```
+
+Then open **http://localhost:8080** in your browser.
+
+The script performs these steps in order:
+
+1. **Framework build** — skipped in standalone mode (framework is an npm dependency); runs `pnpm run build:all` only when inside the framework monorepo
+2. `npx slingr sync-metadata` — regenerates `frontend/generated/` (view registry, GraphQL types)
+3. `npm run build` (in `frontend/`) — produces a minified production bundle in `frontend/dist/`
+4. `docker compose up --build` — builds the backend image and starts all three containers
+
+In monorepo mode, skip rebuilding the framework if only app code changed:
+```bash
+SKIP_FRAMEWORK_BUILD=1 node ops/scripts/test-prod-local.js
+```
+
+### Manual step-by-step
+
+Run from the **app root**:
+
+```bash
+# 1. (Monorepo only) Build the framework and CLI from source
+#    Skip this in standalone mode — the framework is in node_modules
+# pnpm run build:all
+
+# 2. Regenerate view registry and GraphQL types
+npx slingr sync-metadata
+
+# 3. Build the production frontend bundle
+(cd frontend && npm run build)
+
+# 4. Start the full stack
+docker compose \
+  -f docker-compose.yml \
+  -f docker-compose.prod-test.yml \
+  up --build
+
+# Open http://localhost:8080
+```
+
+To tear it down and clean up volumes:
+
+```bash
+docker compose \
+  -f docker-compose.yml \
+  -f docker-compose.prod-test.yml \
+  down -v
+```
+
+### What to verify
+
+| Check | How |
+|---|---|
+| App loads at `http://localhost:8080` | No blank page, no console errors on startup |
+| Login works | Authenticate with the seeded user (`sys@app.com`) |
+| Toolbar buttons navigate correctly | Click every toolbar button — a `View class "X" is not registered` error means class name minification is breaking the view registry |
+| Dashboard loads without errors | Open the dashboard — a `Failed to construct 'URL': Invalid URL` error means `GraphQLClientService.baseUrl` is a relative path that `graphql-request` cannot handle |
+| Create / update forms submit | Submit a create form — `Runtime Object type "ExpectedErrorType" is not a possible type` means the GraphQL union type is missing `ExpectedErrorType` in the schema |
+| Backend logs look clean | `docker compose logs backend` — no startup crashes |
+
+### Iterating quickly
+
+After fixing a frontend issue (run from app root):
+
+```bash
+(cd frontend && npm run build)
+
+docker compose \
+  -f docker-compose.yml \
+  -f docker-compose.prod-test.yml \
+  restart frontend
+```
+
+After fixing a backend issue (run from app root):
+
+```bash
+docker compose \
+  -f docker-compose.yml \
+  -f docker-compose.prod-test.yml \
+  up --build backend
+```
+
+---
+
+## Step 3 — One-Time GCP Infrastructure Setup
+
+Run once per GCP project. The script is idempotent — safe to re-run.
+
+Run from the **app root**:
+
+```bash
+node ops/scripts/setup-gcp.js
+
+# Override project or region:
+PROJECT_ID=my-project REGION=europe-west1 node ops/scripts/setup-gcp.js
+```
+
+### What it creates
+
+| Resource | Example name | Notes |
+|---|---|---|
+| APIs enabled | Cloud Run, Cloud SQL, Artifact Registry, Cloud Build, Secret Manager, Cloud Storage, Compute Engine | ~1 minute on first run |
+| Artifact Registry repo | `slingr-apps` | Shared Docker registry across all apps in the project |
+| Cloud SQL instance | `<app>-db` | PostgreSQL 15, `db-f1-micro` tier |
+| Cloud SQL database | `<your_db_name>` | Created inside the instance |
+| Cloud SQL user | `postgres` | Password set interactively |
+| Backend service account | `<app>-backend@PROJECT.iam.gserviceaccount.com` | Runtime identity for Cloud Run |
+| IAM bindings (backend SA) | `roles/cloudsql.client`, `roles/secretmanager.secretAccessor` | Minimum required at runtime |
+| IAM bindings (Cloud Build SA) | `roles/run.admin`, `roles/iam.serviceAccountUser`, `roles/secretmanager.secretAccessor`, `roles/artifactregistry.writer`, `roles/cloudsql.client`, `roles/storage.objectAdmin` | Required for automated CI/CD |
+| GCS bucket | `PROJECT_ID-<app>-frontend` | Public, SPA routing via `index.html` |
+| Serverless NEG | `<app>-backend-neg` | Routes Load Balancer traffic to Cloud Run |
+| Backend service | `<app>-backend-service` | Wraps the NEG |
+| Backend bucket | `<app>-frontend-bucket` | CDN-backed, wraps the GCS bucket |
+| URL map | `<app>-url-map` | `/graphql` and `/auth/*` → Cloud Run; `/**` → GCS |
+| HTTP proxy + forwarding rule | `<app>-http-proxy`, `<app>-http-rule` | Port 80; see [Step 7](#step-7--dns--https-setup-optional) to add HTTPS |
+
+### After running
+
+The script prints the Load Balancer IP. Note it — this is the app's public IP until you configure a custom domain.
+
+---
+
+## Step 4 — Secrets Management
+
+Run after `setup-gcp.js`. Can be re-run at any time to rotate credentials.
+
+Run from the **app root**:
+
+```bash
+node ops/scripts/setup-secrets.js
+
+# Override project:
+PROJECT_ID=my-project node ops/scripts/setup-secrets.js
+```
+
+The script prompts for:
+
+| Secret name | What to enter |
+|---|---|
+| `<app>-db-password` | The password you set on the Cloud SQL `postgres` user during `setup-gcp.js` |
+| `<app>-jwt-secret` | Any long random string — press Enter to auto-generate |
+
+Both secrets are created in Secret Manager and the backend service account is granted access to each.
+
+### Rotating secrets later
+
+Re-run the script — it adds a new secret version automatically. Cloud Run picks up the new version on the next cold start. To force immediate pickup:
+
+```bash
+gcloud run services update <app>-backend \
+  --region=REGION \
+  --no-traffic \
+  --project=PROJECT_ID
+```
+
+---
+
+## Step 5 — Cloud Build Trigger (Automated Deploys)
+
+### Connect the GitHub repository (one-time)
+
+Before creating the trigger, connect your repo to Cloud Build:
+
+```
+https://console.cloud.google.com/cloud-build/triggers/connect
+```
+
+Or via CLI:
+
+```bash
+gcloud builds connections create github <CONNECTION_NAME> --region=$REGION
+gcloud builds repositories create <REPO_NAME> \
+  --remote-uri=https://github.com/<ORG>/<REPO>.git \
+  --connection=<CONNECTION_NAME> \
+  --region=$REGION
+```
+
+### Create the trigger
+
+```bash
+PROJECT_ID="your-project-id"
+REGION="us-central1"
+GITHUB_ORG="your-github-org"
+APP="{{APP_NAME}}"
+DB_NAME="{{APP_NAME}}"
+
+gcloud builds triggers create github \
+  --project="$PROJECT_ID" \
+  --name="${APP}-deploy-develop" \
+  --repo-name="deployment-support" \
+  --repo-owner="$GITHUB_ORG" \
+  --branch-pattern="^develop$" \
+  --build-config="ops/cloudbuild.yaml" \
+  --substitutions="\
+_PROJECT_ID=$PROJECT_ID,\
+_REGION=$REGION,\
+_AR_REPO=slingr-apps,\
+_BACKEND_SERVICE=${APP}-backend,\
+_BACKEND_SA=${APP}-backend@${PROJECT_ID}.iam.gserviceaccount.com,\
+_CLOUDSQL_INSTANCE=${PROJECT_ID}:${REGION}:${APP}-db,\
+_DB_SECRET_NAME=${APP}-db-password,\
+_JWT_SECRET_NAME=${APP}-jwt-secret"
+```
+
+### cloudbuild.yaml structure
+
+The `cloudbuild.yaml` uses substitution variables so the same file works for any project. The pipeline:
+
+1. **pull-backend-cache** — pulls `:latest` from Artifact Registry (cache for subsequent builds)
+2. **build-backend** — builds the Docker image from the app root with `--cache-from`
+3. **push-backend** — pushes `:COMMIT_SHA` and `:latest` tags
+4. **schema-sync** — creates/updates and executes the `<app>-migrate` Cloud Run Job (`DB_SYNCHRONIZE=true`)
+5. **deploy-backend** — deploys the Cloud Run service (`DB_SYNCHRONIZE=false`); runs after schema-sync
+6. **build-frontend** — installs app dependencies, runs `slingr sync-metadata`, builds the SPA (runs in parallel with schema-sync after push-backend)
+7. **deploy-frontend** — syncs `frontend/dist/` to GCS bucket
+
+> **Steps 4 and 6 run in parallel** (`waitFor: [push-backend]`), reducing total pipeline time.
+
+---
+
+## Step 6 — Manual Deployment
+
+Run from the **app root**:
+
+```bash
+# Deploy HEAD
+node ops/scripts/deploy.js
+
+# Deploy a specific tag
+node ops/scripts/deploy.js v1.2.3
+```
+
+The script:
+
+| Step | What happens |
+|---|---|
+| 0 | (Monorepo only) Builds framework + CLI from source; generates metadata (`slingr sync-metadata`); compiles backend + frontend |
+| 1 | `docker build` with `--cache-from :latest` |
+| 2 | `docker push` (`:SHA` and `:latest`) |
+| 3 | Creates/updates and executes the `<app>-migrate` Cloud Run Job |
+| 4 | Seeds default admin user via Cloud SQL Proxy (skipped if user already exists) |
+| 5 | `gcloud run deploy <app>-backend` |
+| 6 | `gsutil -m rsync -r -d frontend/dist gs://PROJECT_ID-<app>-frontend` |
+
+---
+
+## Step 7 — DNS & HTTPS Setup (Optional)
+
+> **You need to own a domain before running this step.** Google does not provide a domain — you purchase one from a registrar (Namecheap, GoDaddy, Google/Squarespace Domains, etc.), typically for $10–20/year. Without a domain, the app continues to work over HTTP on the Load Balancer IP. HTTPS with a custom domain is an optional production step.
+
+> **This step can be done any time after `setup-gcp.js`** — even weeks after the first deployment. The Load Balancer created in Step 3 is the only prerequisite.
+
+By default, `setup-gcp.js` creates an HTTP (port 80) Load Balancer with an ephemeral IP. Run `setup-domain.js` to add a static IP, SSL certificate, and HTTPS:
+
+Run from the **app root**:
+
+```bash
+DOMAIN=app.yourdomain.com node ops/scripts/setup-domain.js
+
+# Override project or region:
+PROJECT_ID=my-project REGION=us-central1 DOMAIN=app.yourdomain.com \
+  node ops/scripts/setup-domain.js
+```
+
+### What setup-domain.js does
+
+The script is idempotent — safe to re-run:
+
+1. **Reserves a static global IP** (`<app>-ip`) — replaces the ephemeral IP on the forwarding rule
+2. **Creates a Google-managed SSL certificate** (`<app>-cert`) for your domain — Google provisions and auto-renews it at no extra cost
+3. **Creates an HTTPS target proxy** (`<app>-https-proxy`) pointing at the existing URL map
+4. **Creates an HTTPS forwarding rule** (`<app>-https-rule`) on port 443 using the static IP
+5. **Prints the static IP** and the DNS record you need to configure
+
+### After running setup-domain.js
+
+1. **Configure DNS at your domain registrar:**
+   Add an `A` record pointing your domain to the static IP printed by the script.
+
+   ```
+   Type: A
+   Name: app  (or @ for root domain)
+   Value: <static IP from script output>
+   TTL: 300
+   ```
+
+2. **Wait for certificate provisioning** — Google-managed certificates are provisioned automatically after DNS propagates. This takes **10–60 minutes**.
+
+3. **Verify the certificate is active:**
+   ```bash
+   gcloud compute ssl-certificates describe <app>-cert --global \
+     --format='value(managed.status, managed.domainStatus)'
+   ```
+   Status should be `ACTIVE`. If it shows `PROVISIONING`, wait and check again.
+
+4. **Test your HTTPS endpoint:**
+   ```bash
+   curl -I https://app.yourdomain.com/graphql
+   ```
+
+### Manual equivalent (no script)
+
+If you prefer running the steps manually:
+
+```bash
+# 1. Reserve a static IP
+gcloud compute addresses create <app>-ip --global
+
+# 2. Get the static IP
+gcloud compute addresses describe <app>-ip --global --format='value(address)'
+
+# 3. Create a Google-managed SSL certificate
+gcloud compute ssl-certificates create <app>-cert \
+  --domains=app.yourdomain.com \
+  --global
+
+# 4. Create HTTPS target proxy
+gcloud compute target-https-proxies create <app>-https-proxy \
+  --url-map=<app>-url-map \
+  --ssl-certificates=<app>-cert \
+  --global
+
+# 5. Create HTTPS forwarding rule
+gcloud compute forwarding-rules create <app>-https-rule \
+  --load-balancing-scheme=EXTERNAL_MANAGED \
+  --global \
+  --target-https-proxy=<app>-https-proxy \
+  --ports=443 \
+  --address=<app>-ip
+```
+
+---
+
+## Networking
+
+The networking layer is fully provisioned by `setup-gcp.js`. No manual network configuration is required after running that script.
+
+### What was set up
+
+```
+Internet → Cloud HTTP(S) Load Balancer (global, external)
+             │
+             ├── URL map: /graphql, /auth/* → Backend Service
+             │              └── Serverless NEG → Cloud Run service
+             │
+             └── URL map: /** (default) → Backend Bucket
+                            └── GCS Bucket (CDN-backed)
+```
+
+| Component | Name | Purpose |
+|---|---|---|
+| Forwarding rule | `<app>-http-rule` (port 80) | Accepts incoming HTTP traffic |
+| HTTP target proxy | `<app>-http-proxy` | Routes requests to the URL map |
+| URL map | `<app>-url-map` | Path-based routing rules |
+| Serverless NEG | `<app>-backend-neg` | Connects the LB to the Cloud Run service |
+| Backend service | `<app>-backend-service` | Wraps the NEG for the URL map |
+| Backend bucket | `<app>-frontend-bucket` | Wraps the GCS bucket with CDN |
+| GCS bucket | `PROJECT_ID-<app>-frontend` | Serves the React SPA static files |
+
+### Cloud SQL connectivity
+
+Cloud Run connects to Cloud SQL through the **Cloud SQL Auth Proxy** — a built-in sidecar that Google manages automatically. No VPC Connector, no firewall rules, and no open database ports are needed. The connection is:
+
+- **Authenticated** via the backend service account IAM role (`roles/cloudsql.client`)
+- **Encrypted** in transit automatically
+- **Socket-based** inside the container: `DB_HOST=/cloudsql/PROJECT:REGION:INSTANCE`
+
+### Verifying the networking setup
+
+```bash
+# Check the Load Balancer forwarding rules
+gcloud compute forwarding-rules list --global
+
+# Inspect the URL map routing rules
+gcloud compute url-maps describe <app>-url-map --global
+
+# Get the Load Balancer's public IP
+gcloud compute forwarding-rules describe <app>-http-rule \
+  --global --format='value(IPAddress)'
+
+# Check the serverless NEG
+gcloud compute network-endpoint-groups describe <app>-backend-neg \
+  --region=REGION
+```
+
+---
+
+## Frontend Hosting
+
+The React SPA is built with UmiJS (`npm run build` → `frontend/dist/`) and served from a GCS bucket behind the Cloud Load Balancer.
+
+### URL routing
+
+| Path pattern | Destination |
+|---|---|
+| `/graphql` | Cloud Run backend (via serverless NEG) |
+| `/auth/*` | Cloud Run backend (via serverless NEG) |
+| `/**` (default) | GCS bucket CDN |
+
+API calls use relative paths (`/graphql`, `/auth/...`). The LB routes them to the backend — no CORS issues, no hardcoded URLs.
+
+### Manual frontend deploy
+
+Run from the **app root**:
+
+```bash
+cd frontend
+npm ci && npm run build
+
+gsutil -m rsync -r -d dist gs://YOUR_PROJECT_ID-<app>-frontend
+```
+
+### CDN cache invalidation
+
+After deploying new frontend files, force immediate CDN propagation:
+
+```bash
+gcloud compute url-maps invalidate-cdn-cache <app>-url-map \
+  --path="/*" --global
+```
+
+---
+
+## Database Schema Sync
+
+TypeORM's `synchronize: true` is **disabled in production** to prevent accidental table drops. Schema updates are handled by a dedicated Cloud Run Job before each deployment:
+
+```
+Cloud Run Job: <app>-migrate
+  Image: same backend image, new tag
+  Env: DB_SYNCHRONIZE=true, NODE_ENV=migration
+  Runs once → exits after schema is in sync
+  → Production service deploys after job exits 0
+```
+
+The job is created on first run and updated on every subsequent deploy. On the very first deployment to a fresh database, the schema-sync job creates all tables — no manual SQL needed.
+
+---
+
+## Default Admin User
+
+`deploy.js` seeds a default admin user on the first deployment (idempotent — skipped if the user already exists). Configure the credentials in `deploy.js`:
+
+```bash
+SEED_USER_EMAIL="sys@app.com"
+SEED_USER_PASS="123456788"
+```
+
+The seed runs locally via the Cloud SQL Auth Proxy, using the DB password fetched from Secret Manager. **Change the password immediately after first login.**
+
+---
+
+## Logging & Observability
+
+Cloud Run services automatically ship all stdout/stderr to **Cloud Logging** — no configuration is required. Logs are available immediately after the first request.
+
+### View backend logs
+
+```bash
+gcloud logging read \
+  'resource.type="cloud_run_revision" AND resource.labels.service_name="<app>-backend"' \
+  --project=PROJECT_ID \
+  --limit=50 \
+  --format='table(timestamp, severity, textPayload)'
+```
+
+### Stream live logs
+
+```bash
+gcloud beta run services logs tail <app>-backend --region=REGION
+```
+
+### Useful log filters
+
+| What to find | Filter |
+|---|---|
+| All backend logs | `resource.type="cloud_run_revision" resource.labels.service_name="<app>-backend"` |
+| Errors only | `resource.type="cloud_run_revision" resource.labels.service_name="<app>-backend" severity>=ERROR` |
+| Schema sync job | `resource.type="cloud_run_job" resource.labels.job_name="<app>-migrate"` |
+| DB connection errors | `resource.type="cloud_run_revision" textPayload:"connection refused" OR textPayload:"authentication failed"` |
+| Specific request | `resource.type="cloud_run_revision" httpRequest.requestUrl:"/graphql"` |
+
+Copy these filters into the [Cloud Console Logs Explorer](https://console.cloud.google.com/logs/query).
+
+### Cloud Monitoring — uptime check
+
+Create an uptime check to monitor backend availability and receive alerts if the service goes down:
+
+```bash
+gcloud monitoring uptime create \
+  --display-name="<app>-backend uptime" \
+  --resource-type=uptime-url \
+  --uri="http://<LB_IP>/graphql" \
+  --check-interval=300 \
+  --project=PROJECT_ID
+```
+
+> Replace `<LB_IP>` with your Load Balancer IP (or custom domain if configured). Attach a notification channel in [Cloud Console → Monitoring → Alerting](https://console.cloud.google.com/monitoring/alerting).
+
+### Cloud Monitoring — error rate alert
+
+Create a log-based metric and alert policy to notify when backend errors spike:
+
+```bash
+# Create a log-based metric for backend errors
+gcloud logging metrics create <app>-backend-errors \
+  --description="Count of ERROR+ logs from the backend" \
+  --log-filter='resource.type="cloud_run_revision" resource.labels.service_name="<app>-backend" severity>=ERROR' \
+  --project=PROJECT_ID
+
+# Create an alert policy (fires if >5 errors in 5 minutes)
+gcloud alpha monitoring policies create \
+  --policy='{
+    "displayName": "<app>-backend error spike",
+    "conditions": [{
+      "displayName": "Error log count",
+      "conditionThreshold": {
+        "filter": "metric.type=\"logging.googleapis.com/user/<app>-backend-errors\"",
+        "comparison": "COMPARISON_GT",
+        "thresholdValue": 5,
+        "duration": "300s",
+        "aggregations": [{"alignmentPeriod": "300s", "perSeriesAligner": "ALIGN_RATE"}]
+      }
+    }],
+    "alertStrategy": {"autoClose": "604800s"},
+    "combiner": "OR",
+    "enabled": true
+  }' \
+  --project=PROJECT_ID
+```
+
+> Attach a notification channel (email, Slack, PagerDuty) in [Cloud Console → Monitoring → Alerting](https://console.cloud.google.com/monitoring/alerting) after creating the policy.
+
+---
+
+## IAM & Service Accounts Reference
+
+### Runtime service account (`<app>-backend`)
+
+| Role | Purpose |
+|---|---|
+| `roles/cloudsql.client` | Connect to Cloud SQL via Auth Proxy at runtime |
+| `roles/secretmanager.secretAccessor` | Read DB password and JWT secret at container startup |
+
+### Cloud Build service account (CI/CD)
+
+| Role | Purpose |
+|---|---|
+| `roles/run.admin` | Deploy Cloud Run services and jobs |
+| `roles/iam.serviceAccountUser` | Act as the backend SA when deploying Cloud Run |
+| `roles/secretmanager.secretAccessor` | Read secrets referenced in `cloudbuild.yaml` |
+| `roles/artifactregistry.writer` | Push Docker images to Artifact Registry |
+| `roles/cloudsql.client` | Execute the schema-sync Cloud Run Job |
+| `roles/storage.objectAdmin` | Sync frontend files to the GCS bucket |
+
+---
+
+## Ongoing Operations
+
+### Roll back to a previous revision
+
+```bash
+# List recent revisions
+gcloud run revisions list --service=<app>-backend --region=REGION
+
+# Send 100% traffic to a previous revision
+gcloud run services update-traffic <app>-backend \
+  --to-revisions=<app>-backend-00005-xyz=100 --region=REGION
+```
+
+### Scale to zero immediately
+
+```bash
+gcloud run services update <app>-backend \
+  --min-instances=0 --region=REGION
+```
+
+### Connect to Cloud SQL from your local machine
+
+```bash
+# Start proxy
+cloud-sql-proxy PROJECT:REGION:<app>-db --port=5432 &
+
+# Connect
+psql -h 127.0.0.1 -U postgres -d <your_db_name>
+```
+
+---
+
+## Troubleshooting
+
+### Backend fails to connect to Cloud SQL
+
+**Symptom:** `connect ENOENT /cloudsql/PROJECT:REGION:INSTANCE/.s.PGSQL.5433`
+
+The socket file is always `.s.PGSQL.5432`. If the error shows `5433`, `DB_PORT` is wrong:
+
+```bash
+gcloud run services update <app>-backend \
+  --region=REGION \
+  --update-env-vars=DB_PORT=5432 \
+  --project=PROJECT_ID
+```
+
+**Other checks:**
+
+1. Verify `--add-cloudsql-instances` is set:
+   ```bash
+   gcloud run services describe <app>-backend --region=REGION \
+     --format='value(spec.template.metadata.annotations)'
+   ```
+2. Verify the backend SA has `roles/cloudsql.client`:
+   ```bash
+   gcloud projects get-iam-policy PROJECT_ID --flatten="bindings[].members" \
+     --filter="bindings.members:<app>-backend@*"
+   ```
+3. Check `DB_HOST` matches the instance connection name exactly: `PROJECT:REGION:INSTANCE`
+
+### Cloud Run service fails to start
+
+**Symptom:** Deployment succeeds but health check fails → rollback
+
+1. Check startup logs: `gcloud beta run services logs tail <app>-backend --region=REGION`
+2. Verify all secrets exist: `gcloud secrets list --project=PROJECT_ID`
+
+**Symptom:** `password authentication failed for user "postgres"`
+
+The DB password and the Secret Manager secret are out of sync:
+
+```bash
+NEW_PASS="$(openssl rand -base64 24)"
+
+gcloud sql users set-password postgres \
+  --instance=<app>-db \
+  --password="$NEW_PASS" \
+  --project=PROJECT_ID
+
+echo -n "$NEW_PASS" | gcloud secrets versions add <app>-db-password \
+  --data-file=- --project=PROJECT_ID
+```
+
+Then redeploy.
+
+### Schema sync job exits non-zero
+
+**Symptom:** `<app>-migrate` job execution fails
+
+1. Check job logs:
+   ```bash
+   gcloud logging read \
+     'resource.type="cloud_run_job" resource.labels.job_name="<app>-migrate"' \
+     --limit=20 --format='value(textPayload)'
+   ```
+2. TypeORM exits 0 even when schema is already up to date — non-zero indicates a real error
+3. Verify `DB_HOST` socket path is correct in the job's env vars
+
+### Docker build fails: `cannot find module '@slingr/framework-backend'`
+
+The Docker build context must be the **app root**, not `backend/`:
+
+```bash
+# Run from your app root (the directory containing backend/ and frontend/)
+docker build -f backend/Dockerfile .
+#                                   ^ app root
+```
+
+### Docker push fails: Unauthenticated request
+
+**Symptom:** `Unauthenticated requests do not have permission "artifactregistry.repositories.uploadArtifacts"`
+
+Configure `gcloud` as the Docker credential helper (runs once per machine):
+
+```bash
+gcloud auth configure-docker us-central1-docker.pkg.dev
+```
+
+If the error persists, ensure you are logged in with an account that has `roles/artifactregistry.writer`:
+
+```bash
+gcloud auth login
+gcloud auth configure-docker us-central1-docker.pkg.dev
+```
+
+### Cloud SQL Proxy is not recognized on local machine
+
+**Symptom:** `"cloud-sql-proxy" is not recognized as an internal or external command`
+
+Install the component and open a new terminal:
+
+```bash
+gcloud components install cloud-sql-proxy
+cloud-sql-proxy --version
+```
+
+On Windows, restart your terminal (or VS Code) after install so `PATH` is refreshed.
+
+### Frontend not updating after deploy
+
+**Symptom:** Old files served despite successful `gsutil rsync`
+
+Force CDN cache invalidation:
+
+```bash
+gcloud compute url-maps invalidate-cdn-cache <app>-url-map \
+  --path="/*" --global
+```
+
+### Load Balancer returns 404 for frontend routes
+
+**Symptom:** Navigating directly to `/dashboard` returns 404
+
+The GCS bucket must have its 404 page set to `index.html`:
+
+```bash
+gcloud storage buckets describe gs://PROJECT_ID-<app>-frontend \
+  --format='value(website)'
+```
+
+If missing:
+
+```bash
+gcloud storage buckets update gs://PROJECT_ID-<app>-frontend \
+  --web-main-page-suffix=index.html \
+  --web-error-page=index.html
+```
+
+### SSL certificate stuck in PROVISIONING
+
+**Symptom:** `gcloud compute ssl-certificates describe <app>-cert --global` shows `PROVISIONING` for more than 2 hours
+
+1. Verify the DNS A record points to the correct static IP:
+   ```bash
+   dig +short app.yourdomain.com
+   gcloud compute addresses describe <app>-ip --global --format='value(address)'
+   ```
+2. Ensure the forwarding rules use the **static IP** (not the old ephemeral one). `setup-domain.js` handles this automatically.
+3. Certificate provisioning requires the domain to resolve to the LB IP globally. Use [dnschecker.org](https://dnschecker.org) to verify propagation across regions.