For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /pt/docs/web/deploy-google-cloud.md (or send Accept: text/markdown).
Implementar no Google Cloud
Construa a imagem Docker do kit no Cloud Build, execute-a no Cloud Run com segredos geridos e coloque-a no seu domínio.
Passo a passo para iniciantes
Pré-requisitos: a app a funcionar em local, um banco de dados real acessível a partir da internet (Configurar a base de dados) e as contas de provedor dos recursos que lança. Precisa de uma conta Google; a configuração da faturação pede um cartão embora o uso ligeiro se mantenha dentro do free tier.
Terminologia rápida: uma imagem de contentor é uma cópia empacotada da sua app que qualquer host consegue executar. Artifact Registry é o armazém de imagens da Google. Cloud Build constrói a imagem nas máquinas da Google — não é preciso Docker local. Cloud Run executa a imagem como serviço HTTPS e escala-a. Secret Manager guarda palavras-passe e chaves. Uma revisão é uma versão implementada do serviço.
O que vai construir: um projeto Google Cloud, um repositório Artifact Registry a guardar a sua imagem, um serviço Cloud Run a servir a app por HTTPS, segredos no Secret Manager e um Postgres gerido. O Dockerfile da raiz do kit já produz um servidor Next.js standalone a escutar na porta 8080 — exatamente o que o Cloud Run espera.
Nota honesta sobre custos: o free tier do Cloud Run cobre tráfego ligeiro, mas o Cloud SQL — o Postgres gerido da Google — não tem free tier. Um banco de dados Supabase ou Neon em free tier é a forma mais barata de começar; este guia usa esse caminho. Considere adicionar um alerta de orçamento em Billing → Budgets & alerts antes de experimentar.
Criar a conta e instalar a CLI
1. Abra console.cloud.google.com, inicie sessão com a sua conta Google e aceite os termos.
2. Associe a faturação quando solicitado: Billing → Link a billing account → Create billing account. Um cartão é necessário para ativar a conta; o crédito de teste cobre as primeiras experiências.
3. Clique no menu de projeto → New Project, dê-lhe um nome e Create — ou reutilize o projeto que criou para o início de sessão com Google; um único projeto chega.
4. Instale a Google Cloud CLI a partir de cloud.google.com/sdk: descarregue o instalador do seu sistema operativo, conclua-o e abra um terminal novo para o comando gcloud ficar disponível.
5. Execute os dois comandos abaixo. O primeiro abre um navegador para autorizar a CLI; o segundo seleciona o seu projeto — use o ID de projeto mostrado no painel da consola, que nem sempre coincide com o nome.
Esperado: gcloud config list mostra a sua conta e projeto. Se gcloud não for reconhecido, reabra o terminal ou conclua primeiro o instalador.
gcloud auth login
gcloud config set project YOUR_PROJECT_IDCriar o banco de dados de produção
Caminho para principiantes — Postgres gerido fora da Google. Em supabase.com: New project → escolha nome, palavra-passe do banco e região → aguarde o aprovisionamento → Project Settings → Database. O Supabase oferece duas cadeias de ligação: o session pooler / ligação direta na porta 5432 e o transaction pooler na porta 6543 — a cadeia 5432 é para migrações e clientes long-lived, a 6543 para a app serverless. Em neon.tech: New project → copie a cadeia de ligação mostrada. Qualquer uma serve; mantenha intacta a parte da palavra-passe.
Coloque a cadeia direct/session em DATABASE_URL do .env da raiz — a ferramenta de migração lê o ficheiro da raiz e precisa de uma ligação session — e em apps/web/.env.local para o servidor de desenvolvimento local. Depois execute o comando de migração uma vez a partir da raiz do repositório para criar as tabelas do kit no novo banco. O segredo DATABASE_URL usado pela app implementada pode ser, em vez disso, a cadeia pooled 6543.
A alternativa nativa da Google é o Cloud SQL, um Postgres gerido dentro do mesmo projeto. Não tem free tier e as ligações por IP privado exigem um conector VPC — trate-o como uma melhoria posterior, não como ponto de partida.
# DATABASE_URL=<the direct/session Postgres string, port 5432> in .env + apps/web/.env.local, then:
corepack pnpm --filter @supastack/db db:migrateAtivar serviços e enviar a imagem
Execute os comandos abaixo a partir da raiz do repositório. Ativam os quatro serviços Google que esta implementação usa, criam um repositório Docker no Artifact Registry e submetem o repositório ao Cloud Build — que constrói o Dockerfile da raiz remotamente, por isso o Docker Desktop não é necessário.
Substitua YOUR_PROJECT_ID e escolha uma região — us-central1 abaixo — e reutilize-a para o repositório e o serviço. Esperado: o log da build corre durante vários minutos e termina com DONE / STATUS: SUCCESS. A imagem aparece depois na consola em 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:latestGuardar os segredos no Secret Manager
Os segredos nunca vão em --set-env-vars nem na imagem — ambos são armazenados em texto simples e visíveis para quem possa ler a configuração do serviço. O Secret Manager mantém-nos cifrados e injeta-os em tempo de execução.
1. Na consola, abra Security → Secret Manager → Create Secret.
2. Crie DATABASE_URL com a cadeia de ligação Postgres completa — a cadeia serverless pooled serve para a app — AUTH_SECRET com pelo menos 32 caracteres aleatórios (openssl rand -hex 32 gera um) e CREDENTIAL_ENCRYPTION_KEY com uma chave de 32 bytes codificada em Base64 (openssl rand -base64 32); cifra as chaves de provedor que os workspaces guardam na app.
3. Crie um segredo por provedor ativado — por exemplo STRIPE_SECRET_KEY mais STRIPE_WEBHOOK_SECRET, RESEND_API_KEY, GOOGLE_CLIENT_SECRET, GITHUB_CLIENT_SECRET. Definições não secretas como EMAIL_PROVIDER=resend ficam como variáveis de ambiente normais, não segredos.
Na primeira vez que um serviço referencia um segredo, a sua conta de serviço de execução precisa de permissão para o ler — quando anexa segredos pelo editor de serviço da consola, a Google oferece essa concessão automaticamente; na CLI, o erro de implementação nomeia a role de Secret Manager a conceder.
# 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_SECRETImplementar o serviço Cloud Run
Caminho pela consola: Cloud Run → Create service → Deploy one revision from an existing container image → selecione a imagem …/supastack/web:latest enviada → escolha a mesma região → em Authentication escolha Allow unauthenticated invocations (é uma app pública) → Create.
O equivalente em CLI abaixo adiciona a ligação do ambiente no mesmo passo. A configuração em texto simples vai em --set-env-vars; os segredos são referenciados pelo nome no Secret Manager em --set-secrets. Adicione as suas flags de provedor (EMAIL_PROVIDER, BILLING_PROVIDER, AI_PROVIDER, JOB_PROVIDER) como variáveis de ambiente normais ao lado de APP_URL.
APP_ENV=production é obrigatório — sem ele a app arranca em modo local: a validação da configuração de produção é ignorada, os prefixos de cookies seguros ficam desligados e a página só-dev /mail-preview permanece acessível publicamente (expondo a caixa de saída de e-mail local quando EMAIL_PROVIDER=local). A produção exige ainda mais quatro valores no arranque: EXPO_PUBLIC_API_URL é o URL https público que a app mobile usa para chegar à API — defina-o como o URL do serviço (igual a APP_URL numa implementação só web); EXPO_PUBLIC_APP_SCHEME é o esquema de deep link da app mobile — qualquer valor válido como supastack serve quando não lança app mobile; MOBILE_ALLOWED_ORIGINS é a lista, separada por vírgulas, das origens https exatas em que o servidor confia — o URL da sua app é o bom começo, e wildcards são rejeitados; CREDENTIAL_ENCRYPTION_KEY cifra as credenciais de provedor guardadas e fica no Secret Manager.
O Cloud Run atribui um URL https://….run.app na primeira implementação, e o APP_URL da app deve igualar o seu URL público real para que os callbacks de autenticação e os links funcionem. Por isso, implemente uma vez com o placeholder, copie o URL *.run.app da página do serviço e depois atualize o serviço (consola: Edit & deploy new revision, ou execute o comando de novo) com APP_URL — e os valores EXPO_PUBLIC_API_URL / MOBILE_ALLOWED_ORIGINS correspondentes — a apontar para ele. A porta do contentor continua a ser 8080 — a predefinição do Cloud Run já coincide com o PORT do 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"Mapear o seu próprio domínio (opcional)
Salte este passo enquanto testa — o URL *.run.app já serve HTTPS. Quando estiver pronto: Cloud Run → o seu serviço → Custom Domains / Domain Mappings → Add mapping → escolha o serviço e escreva o seu domínio.
Verifique a propriedade do domínio se solicitado (a Google guia-o), depois crie os registos DNS que o ecrã de mapeamento lista junto do seu registrador. O certificado HTTPS gerido é emitido automaticamente quando os registos propagam — normalmente minutos, até um dia.
Quando o domínio servir tráfego, atualize APP_URL para https://yourdomain.com e registe os URI de redirecionamento OAuth correspondentes (https://yourdomain.com/api/auth/callback/…) — os guias de início de sessão indicam onde.
Verificar a implementação
Abra https://YOUR_SERVICE_URL/api/health — espere ok. Depois exercite a app de ponta a ponta: abra o URL, registe-se, peça um código de e-mail, confirme que chega à caixa de entrada (isso exige EMAIL_PROVIDER=resend, RESEND_API_KEY e um remetente verificado — o adaptador local nunca chega a caixas reais), inicie sessão e use um recurso ativado.
Cloud Run → o seu serviço → Logs mostra a saída de pedidos e erros. O separador Revisions oferece rollback com um clique para a revisão anterior se uma implementação correr mal.
Os clientes mobile e desktop devem apontar para este backend HTTPS: EXPO_PUBLIC_API_URL em apps/mobile/.env.local para o Expo, SUPASTACK_APP_URL para o shell de desktop.
Para continuar a configuração, leia Checklist de deployment.