Distribuisci su Google Cloud

Procedura dettagliata per principianti

Prerequisiti: l'app che funziona in locale, un database reale raggiungibile da internet (Configura il database) e gli account dei provider delle funzionalità che lanci. Serve un account Google; l'impostazione della fatturazione chiede una carta anche se un uso leggero resta nel free tier.

Terminologia rapida: un'immagine container è una copia impacchettata della tua app che qualsiasi host può eseguire. Artifact Registry è l'archivio di immagini di Google. Cloud Build costruisce l'immagine sulle macchine di Google — non serve Docker in locale. Cloud Run esegue l'immagine come servizio HTTPS e la scala. Secret Manager custodisce password e chiavi. Una revisione è una versione distribuita del servizio.

Cosa costruisci: un progetto Google Cloud, un repository Artifact Registry che ospita la tua immagine, un servizio Cloud Run che serve l'app via HTTPS, segreti in Secret Manager e un Postgres gestito. Il Dockerfile di root del kit produce già un server Next.js standalone in ascolto sulla porta 8080 — esattamente ciò che Cloud Run si aspetta.

Nota onesta sui costi: il free tier di Cloud Run copre traffico leggero, ma Cloud SQL — il Postgres gestito di Google — non ne ha. Un database Supabase o Neon in free tier è il punto di partenza più economico; questa guida usa quel percorso. Considera di aggiungere un alert di budget sotto Billing → Budgets & alerts prima di sperimentare.

• Configura il database
• Creare prima gli account OAuth

Creare l'account e installare la CLI

1. Apri console.cloud.google.com, accedi con il tuo account Google e accetta i termini.

2. Collega la fatturazione quando richiesto: Billing → Link a billing account → Create billing account. Una carta è necessaria per attivare l'account; il credito di prova copre i primi esperimenti.

3. Fai clic sul menu a discesa del progetto → New Project, assegnagli un nome e Create — oppure riutilizza il progetto che hai creato per l'accesso con Google; un solo progetto va bene.

4. Installa la Google Cloud CLI da cloud.google.com/sdk: scarica l'installer per il tuo sistema operativo, completalo e poi apri un nuovo terminale così il comando gcloud è disponibile.

5. Esegui i due comandi qui sotto. Il primo apre un browser per autorizzare la CLI; il secondo seleziona il tuo progetto — usa l'ID progetto mostrato nel pannello della console, che non sempre coincide con il nome.

Atteso: gcloud config list mostra il tuo account e progetto. Se gcloud non viene riconosciuto, riapri il terminale o completa prima l'installer.

gcloud auth login
gcloud config set project YOUR_PROJECT_ID

Creare il database di produzione

Percorso per principianti — Postgres gestito fuori da Google. Su supabase.com: New project → scegli nome, password del database e regione → attendi il provisioning → Project Settings → Database. Supabase offre due stringhe di connessione: il session pooler / connessione diretta sulla porta 5432 e il transaction pooler sulla porta 6543 — la stringa 5432 serve a migrazioni e client long-lived, la 6543 all'app serverless. Su neon.tech: New project → copia la stringa di connessione mostrata. Entrambe vanno bene; lascia intatta la parte della password.

Metti la stringa direct/session in DATABASE_URL del .env di root — lo strumento di migrazione legge il file di root e ha bisogno di una connessione session — e in apps/web/.env.local per il dev server locale. Poi esegui il comando di migrazione una volta dalla root del repository per creare le tabelle del kit nel nuovo database. Il segreto DATABASE_URL usato dall'app distribuita può invece essere la stringa pooled 6543.

L'alternativa nativa di Google è Cloud SQL, un Postgres gestito dentro lo stesso progetto. Non ha free tier e le connessioni a IP privato richiedono un connettore VPC — trattalo come un upgrade successivo, non come punto di partenza.

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

Abilitare i servizi e fare il push dell'immagine

Esegui i comandi qui sotto dalla root del repository. Abilitano i quattro servizi Google usati da questa distribuzione, creano un repository Docker in Artifact Registry e inviano il repository a Cloud Build — che costruisce il Dockerfile di root da remoto, quindi Docker Desktop non è richiesto.

Sostituisci YOUR_PROJECT_ID e scegli una regione — us-central1 qui sotto — e riutilizzala per repository e servizio. Atteso: il log della build scorre per diversi minuti e termina con DONE / STATUS: SUCCESS. L'immagine appare poi nella console sotto 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

Conservare i segreti in Secret Manager

I segreti non vanno mai in --set-env-vars né nell'immagine — entrambi sono memorizzati in chiaro e visibili a chiunque possa leggere la configurazione del servizio. Secret Manager li tiene cifrati e li inietta a runtime.

1. Nella console apri Security → Secret Manager → Create Secret.

2. Crea DATABASE_URL con la stringa di connessione Postgres completa — la stringa serverless pooled va bene per l'app — AUTH_SECRET con almeno 32 caratteri casuali (openssl rand -hex 32 ne genera uno) e CREDENTIAL_ENCRYPTION_KEY con una chiave a 32 byte codificata in Base64 (openssl rand -base64 32); cifra le chiavi dei provider che i workspace salvano nell'app.

3. Crea un segreto per ogni provider abilitato — ad esempio STRIPE_SECRET_KEY più STRIPE_WEBHOOK_SECRET, RESEND_API_KEY, GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_SECRET. Impostazioni non segrete come EMAIL_PROVIDER=resend restano variabili d'ambiente normali, non segreti.

La prima volta che un servizio fa riferimento a un segreto, il suo service account di runtime ha bisogno del permesso di leggerlo — quando alleghi segreti dall'editor del servizio della console, Google offre automaticamente quella concessione; da CLI, l'errore di distribuzione nomina il ruolo di Secret Manager da concedere.

# 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

Distribuire il servizio Cloud Run

Percorso da console: Cloud Run → Create service → Deploy one revision from an existing container image → seleziona l'immagine …/supastack/web:latest caricata → scegli la stessa regione → sotto Authentication scegli Allow unauthenticated invocations (è un'app pubblica) → Create.

L'equivalente CLI qui sotto aggiunge il cablaggio dell'ambiente nello stesso passaggio. La configurazione in chiaro va in --set-env-vars; i segreti sono referenziati per nome di Secret Manager in --set-secrets. Aggiungi i flag dei provider (EMAIL_PROVIDER, BILLING_PROVIDER, AI_PROVIDER, JOB_PROVIDER) come variabili d'ambiente normali accanto ad APP_URL.

APP_ENV=production è obbligatorio — senza di esso l'app si avvia in modalità local: la validazione della configurazione di produzione viene saltata, i prefissi dei cookie sicuri restano spenti e la pagina solo-dev /mail-preview resta pubblicamente accessibile (facendo trapelare la posta in uscita locale quando EMAIL_PROVIDER=local). La produzione richiede poi altre quattro variabili all'avvio: EXPO_PUBLIC_API_URL è l'URL https pubblico che l'app mobile usa per raggiungere l'API — impostalo sull'URL del servizio (uguale ad APP_URL in una distribuzione solo web); EXPO_PUBLIC_APP_SCHEME è lo schema di deep link dell'app mobile — qualsiasi valore valido come supastack va bene quando non lanci un'app mobile; MOBILE_ALLOWED_ORIGINS è la lista, separata da virgole, delle origini https esatte che il server approva — l'URL della tua app è il giusto inizio, e i caratteri jolly vengono rifiutati; CREDENTIAL_ENCRYPTION_KEY cifra le credenziali dei provider salvate e resta in Secret Manager.

Cloud Run assegna un URL https://….run.app al primo deploy, e l'APP_URL dell'app deve uguagliare il suo URL pubblico reale affinché i callback di autenticazione e i link funzionino. Quindi distribuisci una volta con il placeholder, copia l'URL *.run.app dalla pagina del servizio e poi aggiorna il servizio (console: Edit & deploy new revision, oppure riesegui il comando) con APP_URL — e i valori EXPO_PUBLIC_API_URL / MOBILE_ALLOWED_ORIGINS corrispondenti — puntati su di esso. La porta del container resta 8080 — il valore predefinito di Cloud Run corrisponde già al PORT del 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"

Mappare il proprio dominio (opzionale)

Salta questo passaggio finché testi — l'URL *.run.app serve già HTTPS. Quando sei pronto: Cloud Run → il tuo servizio → Custom Domains / Domain Mappings → Add mapping → scegli il servizio e digita il tuo dominio.

Verifica la proprietà del dominio se richiesto (Google ti guida), poi crea i record DNS elencati dalla schermata di mapping presso il tuo registrar. Il certificato HTTPS gestito viene emesso automaticamente quando i record si propagano — di solito pochi minuti, fino a un giorno.

Quando il dominio serve traffico, aggiorna APP_URL su https://yourdomain.com e registra gli URI di reindirizzamento OAuth corrispondenti (https://yourdomain.com/api/auth/callback/…) — le guide all'accesso indicano dove.

Verificare la distribuzione

Apri https://YOUR_SERVICE_URL/api/health — attendi ok. Poi esercita l'app da cima a fondo: apri l'URL, registrati, richiedi un codice email, conferma che arrivi nella casella di posta (ciò richiede EMAIL_PROVIDER=resend, RESEND_API_KEY e un mittente verificato — l'adattatore locale non raggiunge mai caselle reali), accedi e usa una funzionalità abilitata.

Cloud Run → il tuo servizio → Logs mostra l'output delle richieste e degli errori. La scheda Revisions offre il rollback con un clic alla revisione precedente se una distribuzione va male.

I client mobile e desktop devono puntare a questo backend HTTPS: EXPO_PUBLIC_API_URL in apps/mobile/.env.local per Expo, SUPASTACK_APP_URL per la shell desktop.

• Crea gli account mobile
• Percorrere la checklist di distribuzione completa