Implementeren op Google Cloud

Walkthrough voor beginners

Vereisten: de app lokaal werkend, een echte database die u vanaf het internet kunt bereiken (Database instellen) en de provideraccounts voor de functies die u uitrolt. U heeft een Google-account nodig; de facturatieopstelling vraagt om een kaart ook al blijft licht gebruik binnen de gratis laag.

Snelle begrippen: een containerimage is een verpakte kopie van uw app die elke host kan draaien. Artifact Registry is Google's opslag voor images. Cloud Build bouwt de image op Google's machines — geen lokale Docker nodig. Cloud Run draait de image als HTTPS-dienst en schaalt hem. Secret Manager bewaart wachtwoorden en sleutels. Een revisie is één gedeployde versie van de dienst.

Wat u bouwt: een Google Cloud-project, een Artifact Registry-repository die uw image bevat, een Cloud Run-dienst die de app via HTTPS bedient, geheimen in Secret Manager en een beheerde Postgres. De root-Dockerfile van de kit produceert al een standalone Next.js-server die op poort 8080 luistert — precies wat Cloud Run verwacht.

Eerlijke kostennotitie: de gratis laag van Cloud Run dekt licht verkeer, maar Cloud SQL — Google's beheerde Postgres — heeft geen gratis laag. Een Supabase- of Neon-databank in de gratis laag is de goedkoopste manier om te beginnen; deze gids gebruikt dat pad. Overweeg een budgetmelding toe te voegen onder Billing → Budgets & alerts voordat u experimenteert.

• De database instellen
• Maak eerst de OAuth-accounts aan

Het account aanmaken en de CLI installeren

1. Open console.cloud.google.com, meld u aan met uw Google-account en accepteer de voorwaarden.

2. Koppel facturatie wanneer daarom wordt gevraagd: Billing → Link a billing account → Create billing account. Een kaart is vereist om het account te activeren; proefkrediet dekt de eerste experimenten.

3. Klik op de projectdropdown → New Project, geef het een naam en Create — of hergebruik het project dat u voor Google-login maakte; één project is prima.

4. Installeer de Google Cloud CLI vanaf cloud.google.com/sdk: download het installatieprogramma voor uw besturingssysteem, voltooi het en open daarna een nieuwe terminal zodat het gcloud-commando beschikbaar is.

5. Voer de twee commando's hieronder uit. Het eerste opent een browser om de CLI te autoriseren; het tweede selecteert uw project — gebruik de project-ID die op het consoledashboard staat, die is niet altijd gelijk aan de naam.

Verwacht: gcloud config list toont uw account en project. Als gcloud niet wordt herkend, open de terminal opnieuw of voltooi eerst het installatieprogramma.

gcloud auth login
gcloud config set project YOUR_PROJECT_ID

De productiedatabase aanmaken

Beginnerspad — beheerde Postgres buiten Google. Op supabase.com: New project → kies een naam, databasewachtwoord en regio → wacht op provisioning → Project Settings → Database. Supabase biedt twee verbindingsreeksen: de sessiepooler / directe verbinding op poort 5432 en de transactiepooler op poort 6543 — de 5432-reeks is voor migraties en langdurige clients, de 6543-reeks voor de serverloze app. Op neon.tech: New project → kopieer de getoonde verbindingsreeks. Beide werken; houd het wachtwoordgedeelte intact.

Zet de directe/sessiereeks in DATABASE_URL in de root .env — het migratiehulpmiddel leest het rootbestand en heeft een sessieverbinding nodig — en in apps/web/.env.local voor de lokale devserver. Voer daarna het migrate-commando eenmaal uit vanuit de repositoryroot om de tabellen van de kit in de nieuwe database aan te maken. Het DATABASE_URL-geheim dat de gedeployde app gebruikt mag ook de gepoolde 6543-reeks zijn.

Het Google-native alternatief is Cloud SQL, een beheerde Postgres in hetzelfde project. Het heeft geen gratis laag en private-IP-verbindingen vereisen een VPC-connector — beschouw het als een latere upgrade, geen startpunt.

# DATABASE_URL=<the direct/session Postgres string, port 5432> in .env + apps/web/.env.local, then:
corepack pnpm --filter @supastack/db db:migrate

Diensten inschakelen en de image pushen

Voer de onderstaande commando's uit vanuit de repositoryroot. Ze schakelen de vier Google-diensten in die deze deployment gebruikt, maken een Docker-repository in Artifact Registry en dienen de repository in bij Cloud Build — die de root-Dockerfile op afstand bouwt, dus Docker Desktop is niet vereist.

Vervang YOUR_PROJECT_ID en kies één regio — us-central1 hieronder — en hergebruik die voor de repository en de dienst. Verwacht: het buildlog stroomt enkele minuten en eindigt met DONE / STATUS: SUCCESS. De image verschijnt daarna in de console onder Artifact Registry → supastack → web.

gcloud services enable run.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com secretmanager.googleapis.com

gcloud artifacts repositories create supastack --repository-format=docker --location=us-central1

gcloud builds submit --tag us-central1-docker.pkg.dev/YOUR_PROJECT_ID/supastack/web:latest

Geheimen opslaan in Secret Manager

Geheimen mogen nooit in --set-env-vars of de image terechtkomen — beide worden in platte tekst opgeslagen en zichtbaar voor iedereen die de dienstconfiguratie kan lezen. Secret Manager houdt ze versleuteld en injecteert ze tijdens runtime.

1. Open in de console Security → Secret Manager → Create Secret.

2. Maak DATABASE_URL aan met de volledige Postgres-verbindingsreeks — de gepoolde serverloze reeks is prima voor de app — AUTH_SECRET met minstens 32 willekeurige tekens (openssl rand -hex 32 genereert er een) en CREDENTIAL_ENCRYPTION_KEY met een Base64-gecodeerde 32-bytesleutel (openssl rand -base64 32); die versleutelt de providersleutels die workspaces in de app opslaan.

3. Maak één geheim per ingeschakelde provider — bijvoorbeeld STRIPE_SECRET_KEY plus STRIPE_WEBHOOK_SECRET, RESEND_API_KEY, GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_SECRET. Niet-geheime instellingen zoals EMAIL_PROVIDER=resend blijven gewone omgevingsvariabelen, geen geheimen.

De eerste keer dat een dienst naar een geheim verwijst, heeft haar runtime-serviceaccount toestemming nodig om het te lezen — wanneer u geheimen koppelt via de diensteditor van de console, biedt Google die toekenning automatisch aan; op de CLI noemt de deploymentfout de ontbrekende Secret Manager-rol die u moet toekennen.

# Secrets to create in Secret Manager:
DATABASE_URL     # Postgres connection string — the pooled serverless string is fine
AUTH_SECRET      # openssl rand -hex 32
CREDENTIAL_ENCRYPTION_KEY   # openssl rand -base64 32

# plus one per enabled provider, e.g.:
STRIPE_SECRET_KEY
STRIPE_WEBHOOK_SECRET
RESEND_API_KEY
GOOGLE_CLIENT_SECRET
GITHUB_CLIENT_SECRET

De Cloud Run-dienst deployen

Consolepad: Cloud Run → Create service → Deploy one revision from an existing container image → selecteer de gepushte …/supastack/web:latest-image → kies dezelfde regio → kies onder Authentication de optie Allow unauthenticated invocations (het is een openbare app) → Create.

Het CLI-equivalent hieronder voegt de omgevingsbedrading in dezelfde stap toe. Platte-tekstconfiguratie gaat in --set-env-vars; geheimen worden bij hun Secret Manager-naam gerefereerd in --set-secrets. Voeg uw providervlaggen (EMAIL_PROVIDER, BILLING_PROVIDER, AI_PROVIDER, JOB_PROVIDER) toe als gewone env-vars naast APP_URL.

APP_ENV=production is vereist — zonder start de app in local-modus: productieconfiguratievalidatie wordt overgeslagen, beveiligde cookie-prefixen blijven uit en de dev-only /mail-preview-pagina blijft publiek bereikbaar (wat de lokale e-mailoutbox lekt wanneer EMAIL_PROVIDER=local). Productie vereist daarna nog vier waarden bij het opstarten: EXPO_PUBLIC_API_URL is de publieke https-URL die de mobiele app gebruikt om de API te bereiken — zet die op de dienst-URL (gelijk aan APP_URL bij een web-only deployment); EXPO_PUBLIC_APP_SCHEME is het mobiele deep-link-schema — elke geldige waarde zoals supastack werkt wanneer u geen mobiele app uitrolt; MOBILE_ALLOWED_ORIGINS is de kommagescheiden lijst van exacte https-origins die de server vertrouwt — uw app-URL is het juiste begin, en wildcards worden geweigerd; CREDENTIAL_ENCRYPTION_KEY versleutelt opgeslagen providerinloggegevens en blijft in Secret Manager.

Cloud Run wijst bij de eerste deployment een https://….run.app-URL toe en de APP_URL van de app moet gelijk zijn aan de echte publieke URL voor authcallbacks en links. Deploy dus eenmaal met de placeholder, kopieer de *.run.app-URL van de dienstpagina en werk de dienst daarna bij (console: Edit & deploy new revision, of voer het commando opnieuw uit) met APP_URL — en de bijbehorende EXPO_PUBLIC_API_URL / MOBILE_ALLOWED_ORIGINS-waarden — daarop gezet. De containerpoort blijft 8080 — de Cloud Run-standaard komt al overeen met de PORT van de Dockerfile.

gcloud run deploy supastack --image us-central1-docker.pkg.dev/YOUR_PROJECT_ID/supastack/web:latest --region us-central1 --allow-unauthenticated --set-env-vars "APP_ENV=production,APP_URL=https://YOUR_SERVICE_URL,EXPO_PUBLIC_API_URL=https://YOUR_SERVICE_URL,EXPO_PUBLIC_APP_SCHEME=supastack,MOBILE_ALLOWED_ORIGINS=https://YOUR_SERVICE_URL" --set-secrets "DATABASE_URL=DATABASE_URL:latest,AUTH_SECRET=AUTH_SECRET:latest,CREDENTIAL_ENCRYPTION_KEY=CREDENTIAL_ENCRYPTION_KEY:latest"

Uw eigen domein koppelen (optioneel)

Sla dit over tijdens het testen — de *.run.app-URL bedient al HTTPS. Wanneer u klaar bent: Cloud Run → uw dienst → Custom Domains / Domain Mappings → Add mapping → kies de dienst en voer uw domein in.

Verifieer het domeineigendom als daarom wordt gevraagd (Google begeleidt u erdoorheen) en maak daarna bij uw registrar de DNS-records aan die het mapping-scherm toont. Het beheerde HTTPS-certificaat wordt automatisch uitgegeven nadat de records zijn gepropageerd — meestal minuten, tot een dag.

Nadat het domein verkeer bedient, werk APP_URL bij naar https://yourdomain.com en registreer de bijpassende OAuth redirect-URI's (https://yourdomain.com/api/auth/callback/…) — de logingidsen behandelen waar.

De deployment verifiëren

Open https://YOUR_SERVICE_URL/api/health — verwacht ok. Oefen daarna de app van begin tot eind: open de URL, registreer, vraag een e-mailcode aan, controleer dat die de inbox bereikt (dat vereist EMAIL_PROVIDER=resend, RESEND_API_KEY en een geverifieerde afzender — de lokale adapter bereikt echte inboxen nooit), log in en gebruik een functie die u hebt ingeschakeld.

Cloud Run → uw dienst → Logs toont verzoek- en foutuitvoer. Het tabblad Revisions biedt een rollback met één klik naar de vorige revisie als een deployment misgaat.

Mobiele en desktopclients moeten naar deze HTTPS-backend wijzen: EXPO_PUBLIC_API_URL in apps/mobile/.env.local voor Expo, SUPASTACK_APP_URL voor de desktopshell.

• De mobiele accounts aanmaken
• De volledige deploymentchecklist doorlopen