Auf Google Cloud bereitstellen

Schritt-für-Schritt für Einsteiger

Voraussetzungen: Die App läuft lokal, eine echte Datenbank ist aus dem Internet erreichbar (Datenbank einrichten) und die Anbieter-Konten für Ihre Funktionen existieren. Sie brauchen ein Google-Konto; die Billing-Einrichtung fragt eine Karte ab, auch wenn leichte Nutzung im Free Tier bleibt.

Kurze Begriffe: Ein Container-Image ist eine paketierte Kopie Ihrer App, die jeder Host laufen lassen kann. Artifact Registry ist Googles Speicher für Images. Cloud Build baut das Image auf Googles Maschinen — kein lokales Docker nötig. Cloud Run führt das Image als HTTPS-Dienst aus und skaliert ihn. Secret Manager hält Passwörter und Keys. Eine Revision ist eine deployte Version des Dienstes.

Was Sie bauen: ein Google-Cloud-Projekt, ein Artifact-Registry-Repository mit Ihrem Image, einen Cloud-Run-Dienst, der die App über HTTPS ausliefert, Secrets im Secret Manager und ein verwaltetes Postgres. Das Dockerfile im Repo-Root erzeugt bereits einen standalone Next.js-Server auf Port 8080 — genau das, was Cloud Run erwartet.

Ehrlicher Kostenhinweis: Das Free Tier von Cloud Run deckt leichten Traffic, aber Cloud SQL — Googles verwaltetes Postgres — hat keins. Eine Supabase- oder Neon-Free-Tier-Datenbank ist der günstigste Start; diese Anleitung nutzt diesen Weg. Erwägen Sie einen Budget-Alert unter Billing → Budgets & alerts, bevor Sie experimentieren.

• Die Datenbank einrichten
• Zuerst die OAuth-Konten einrichten

Konto anlegen und CLI installieren

1. Öffnen Sie console.cloud.google.com, melden Sie sich mit Ihrem Google-Konto an und akzeptieren Sie die Bedingungen.

2. Verknüpfen Sie die Abrechnung, wenn Sie dazu aufgefordert werden: Billing → Link a billing account → Create billing account. Zur Aktivierung des Kontos ist eine Karte nötig; das Testguthaben deckt die ersten Experimente.

3. Klicken Sie auf das Projekt-Dropdown → New Project, vergeben Sie einen Namen und Create — oder nutzen Sie das Projekt wieder, das Sie für die Google-Anmeldung angelegt haben; ein Projekt reicht.

4. Installieren Sie die Google Cloud CLI von cloud.google.com/sdk: Laden Sie das Installationsprogramm für Ihr Betriebssystem herunter, führen Sie es aus und öffnen Sie dann ein neues Terminal, damit der gcloud-Befehl verfügbar ist.

5. Führen Sie die beiden Befehle unten aus. Der erste öffnet einen Browser, um die CLI zu autorisieren; der zweite wählt Ihr Projekt — nutzen Sie die Projekt-ID aus dem Console-Dashboard, sie ist nicht immer identisch mit dem Namen.

Erwartet: gcloud config list zeigt Ihr Konto und Projekt. Wird gcloud nicht erkannt, öffnen Sie das Terminal neu oder schließen Sie zuerst die Installation ab.

gcloud auth login
gcloud config set project YOUR_PROJECT_ID

Die Produktionsdatenbank erstellen

Einsteigerweg — verwaltetes Postgres außerhalb von Google. Bei supabase.com: New project → Namen, Datenbankpasswort und Region wählen → auf das Provisioning warten → Project Settings → Database. Supabase bietet zwei Verbindungsstrings: den Session-Pooler / die Direct Connection auf Port 5432 und den Transaction-Pooler auf Port 6543 — der 5432-String ist für Migrationen und langlebige Clients, der 6543-String für die serverlose App. Bei neon.tech: New project → den angezeigten Verbindungsstring kopieren. Beides funktioniert; lassen Sie den Passwortteil intakt.

Setzen Sie den Direct-/Session-String in DATABASE_URL in der .env im Root — das Migrationstool liest die Root-Datei und braucht eine Session-Verbindung — und in apps/web/.env.local für den lokalen Dev-Server. Führen Sie dann den Migrate-Befehl einmal aus dem Repository-Root aus, um die Tabellen des Kits in der neuen Datenbank zu erstellen. Das DATABASE_URL-Secret, das die deployte App nutzt, darf stattdessen der gepoolte 6543-String sein.

Die Google-native Alternative ist Cloud SQL, ein verwaltetes Postgres im selben Projekt. Es hat kein Free Tier, und Private-IP-Verbindungen brauchen einen VPC-Connector — behandeln Sie es als späteres Upgrade, nicht als Startpunkt.

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

Dienste aktivieren und das Image pushen

Führen Sie die Befehle unten aus dem Repository-Root aus. Sie aktivieren die vier Google-Dienste für dieses Deployment, erstellen ein Docker-Repository in Artifact Registry und reichen das Repository bei Cloud Build ein — das das Dockerfile im Root remote baut, sodass Docker Desktop nicht nötig ist.

Ersetzen Sie YOUR_PROJECT_ID und wählen Sie eine Region — unten us-central1 — und nutzen Sie sie für Repository und Dienst gleichermaßen. Erwartet: Das Build-Log streamt einige Minuten und endet mit DONE / STATUS: SUCCESS. Das Image erscheint danach in der Konsole unter 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

Secrets im Secret Manager ablegen

Secrets gehören nie in --set-env-vars oder ins Image — beides liegt im Klartext und ist für jeden sichtbar, der die Dienstkonfiguration lesen kann. Secret Manager hält sie verschlüsselt und injiziert sie zur Laufzeit.

1. Öffnen Sie in der Konsole Security → Secret Manager → Create Secret.

2. Erstellen Sie DATABASE_URL mit dem vollständigen Postgres-Verbindungsstring — der gepoolte serverlose String reicht für die App — AUTH_SECRET mit mindestens 32 Zufallszeichen (openssl rand -hex 32 erzeugt eines) und CREDENTIAL_ENCRYPTION_KEY mit einem Base64-kodierten 32-Byte-Key (openssl rand -base64 32); er verschlüsselt die Anbieter-Keys, die Workspaces in der App speichern.

3. Erstellen Sie ein Secret pro aktiviertem Anbieter — etwa STRIPE_SECRET_KEY plus STRIPE_WEBHOOK_SECRET, RESEND_API_KEY, GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_SECRET. Nicht-geheime Einstellungen wie EMAIL_PROVIDER=resend bleiben einfache Umgebungsvariablen, keine Secrets.

Wenn ein Dienst zum ersten Mal ein Secret referenziert, braucht sein Laufzeit-Service-Account die Lesefreigabe — beim Anhängen von Secrets über den Dienst-Editor der Konsole bietet Google die Freigabe automatisch an; auf der CLI nennt der Deploy-Fehler die zu vergebende Secret-Manager-Rolle.

# 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

Den Cloud-Run-Dienst deployen

Konsolenweg: Cloud Run → Create service → Deploy one revision from an existing container image → das gepushte …/supastack/web:latest-Image auswählen → dieselbe Region wählen → unter Authentication Allow unauthenticated invocations wählen (es ist eine öffentliche App) → Create.

Das CLI-Äquivalent unten ergänzt die Umgebungsverkabelung im selben Schritt. Klartext-Konfiguration kommt in --set-env-vars; Secrets werden über ihren Secret-Manager-Namen in --set-secrets referenziert. Fügen Sie Ihre Anbieter-Flags (EMAIL_PROVIDER, BILLING_PROVIDER, AI_PROVIDER, JOB_PROVIDER) als einfache Env-Vars neben APP_URL hinzu.

APP_ENV=production ist Pflicht — ohne ihn bootet die App im local-Modus: Die Validierung der Produktionskonfiguration wird übersprungen, sichere Cookie-Präfixe bleiben aus, und die Dev-only-Seite /mail-preview bleibt öffentlich erreichbar (sie leakt den lokalen E-Mail-Postausgang bei EMAIL_PROVIDER=local). Produktion verlangt dann vier weitere Werte beim Boot: EXPO_PUBLIC_API_URL ist die öffentliche https-URL, über die die Mobile-App die API erreicht — setzen Sie sie auf die Dienst-URL (für ein reines Web-Deployment identisch mit APP_URL); EXPO_PUBLIC_APP_SCHEME ist das Deep-Link-Scheme der Mobile-App — ein beliebiger gültiger Wert wie supastack reicht, wenn Sie keine Mobile-App ausliefern; MOBILE_ALLOWED_ORIGINS ist die kommagetrennte Liste exakter https-Origins, denen der Server vertraut — Ihre App-URL ist der richtige Anfang, Wildcards werden abgelehnt; CREDENTIAL_ENCRYPTION_KEY verschlüsselt gespeicherte Anbieter-Zugangsdaten und bleibt im Secret Manager.

Cloud Run vergibt beim ersten Deploy eine https://….run.app-URL, und APP_URL der App muss ihrer echten öffentlichen URL entsprechen, damit Auth-Callbacks und Links funktionieren. Deployen Sie also einmal mit dem Platzhalter, kopieren Sie die *.run.app-URL von der Dienstseite und aktualisieren Sie dann den Dienst (Konsole: Edit & deploy new revision, oder den Befehl erneut ausführen) mit APP_URL — und den passenden EXPO_PUBLIC_API_URL-/MOBILE_ALLOWED_ORIGINS-Werten — darauf. Der Container-Port bleibt 8080 — der Cloud-Run-Default passt schon zum PORT des 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"

Eigene Domain verbinden (optional)

Überspringen Sie das beim Testen — die *.run.app-URL liefert schon HTTPS. Wenn Sie bereit sind: Cloud Run → Ihr Dienst → Custom Domains / Domain Mappings → Add mapping → Dienst wählen und Ihre Domain eintragen.

Verifizieren Sie die Domain-Inhaberschaft, falls Sie dazu aufgefordert werden (Google führt Sie durch), und erstellen Sie dann die DNS-Einträge, die der Mapping-Bildschirm bei Ihrem Registrar auflistet. Das verwaltete HTTPS-Zertifikat wird automatisch ausgestellt, sobald die Einträge propagieren — meist Minuten, bis zu einem Tag.

Sobald die Domain Traffic ausliefert, aktualisieren Sie APP_URL auf https://yourdomain.com und registrieren Sie die passenden OAuth-Redirect-URIs (https://yourdomain.com/api/auth/callback/…) — die Sign-in-Guides zeigen, wo.

Das Deployment prüfen

Öffnen Sie https://YOUR_SERVICE_URL/api/health — erwartet wird ok. Testen Sie dann die App Ende zu Ende: URL öffnen, registrieren, einen E-Mail-Code anfordern, bestätigen, dass er im Posteingang ankommt (dazu braucht es EMAIL_PROVIDER=resend, RESEND_API_KEY und einen verifizierten Absender — der lokale Adapter erreicht echte Posteingänge nie), anmelden und eine aktivierte Funktion nutzen.

Cloud Run → Ihr Dienst → Logs zeigt Request- und Fehlerausgaben. Der Revisions-Tab bietet Rollback per Klick auf die vorherige Revision, wenn ein Deploy schiefgeht.

Mobile- und Desktop-Clients müssen auf dieses HTTPS-Backend zeigen: EXPO_PUBLIC_API_URL in apps/mobile/.env.local für Expo, SUPASTACK_APP_URL für die Desktop-Shell.

• Die Mobile-Konten einrichten
• Die komplette Deployment-Checkliste abarbeiten