> ## Documentation Index > Fetch the complete documentation index at: https://supastack.dev/llms.txt > Use this file to discover all available pages before exploring further. > For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt # Distribuisci su Google Cloud Costruisci l'immagine Docker del kit su Cloud Build, eseguila su Cloud Run con segreti gestiti e posizionala sul tuo dominio. ## 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](https://supastack.dev/it/docs/web/setup-database.md) [Creare prima gli account OAuth](https://supastack.dev/it/docs/web/external-accounts.md) ## Creare l'account e installare la CLI 1. Apri [console.cloud.google.com](https://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](https://cloud.google.com/sdk/docs/install): 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](https://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](https://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= 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](https://supastack.dev/it/docs/mobile/external-accounts.md) [Percorrere la checklist di distribuzione completa](https://supastack.dev/it/docs/web/deployment.md) Per continuare la configurazione, leggi [Checklist di deployment](https://supastack.dev/it/docs/web/deployment.md). ## Successivo [Checklist di deployment](https://supastack.dev/it/docs/web/deployment.md)