meguri/docs/deployment.md

GKE and Cloud SQL

Target: GKE, Cloud SQL for PostgreSQL 17, and Cloud SQL Auth Proxy using Workload Identity. PostgreSQL is the durable queue and state store; no Redis is required. Templates are in deploy/. They have not been applied to a cloud project.

1. Provision a private-IP Cloud SQL instance, database and application login; enable backups/PITR. Use a VPC-native GKE cluster with access to the database VPC. Configure Workload Identity and grant its Google service account Cloud SQL Client. Follow Google's GKE connection guide.
2. Build Dockerfile, push your image, and replace project, region, instance, release, service-account, image, and public URL placeholders. Review/pin the proxy image for your rollout; the template uses the version in Google's documented example. Native sidecars are required. Docker/GKE deployment must be validated in your environment.
3. Create the Kubernetes service account and ConfigMap from gke.yaml, then the meguri-secrets Secret through your deployment secret manager. It needs DATABASE_URL=postgresql://USER:PERCENT_ENCODED_PASSWORD@127.0.0.1:5432/meguri. Proxy-to-database transport is encrypted; loopback stays inside the pod. Add tenant-specific JSM _EMAIL / _TOKEN variables only for configured tenants. Never commit rendered secrets.
4. Apply only migrate.yaml, wait for its successful completion, then apply the Deployment, Service and PDB. Migrations use the same image with MEGURI_ROLE=migrate. Replicas have MEGURI_SKIP_MIGRATIONS=true; do not race migrations during rollout.
5. Add your internal HTTPS ingress. MEGURI_PUBLIC_URL must exactly match the browser origin (scheme, host, port); mutations and cookies depend on it. The default Service is ClusterIP. Keep access inside your organization while OIDC is being added. To bootstrap local accounts, temporarily enable signup in that restricted environment, create accounts, then disable signup. Never enable demo seeding outside loopback.
6. Run health checks, a two-user replacement, a tenant-isolation check, and the provider acceptance checklist in testing.md. Enable real JSM integration only after preview and acceptance.

The default Deployment has two replicas serving both web and workers. Conditional database leases serialize each team's publication. Roles can later be split into web and worker deployments without changing the binary. On interruption, a completed remote step remains checkpointed; an unfinished lease expires after five minutes.

Monitor failed/conflict sync jobs, oldest last_success, and window_end approaching the current time. Meguri publishes a finite horizon and must keep running to extend it. Configure operational monitoring around these values; Meguri does not send incident notifications itself. Readiness checks PostgreSQL; liveness checks the process.

The current polling worker and history/audit reads target team-scale workloads. Benchmark and add query pagination/queue batching before broad multi-tenant SaaS rollout. Configure ingress-level rate limits in addition to per-process login throttling. Password recovery, session administration, OIDC, history archival, and live provider acceptance are subsequent operational work.