> ## 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 # 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. [Configurar a base de dados](https://supastack.dev/pt/docs/web/setup-database.md) [Criar primeiro as contas OAuth](https://supastack.dev/pt/docs/web/external-accounts.md) ## Criar a conta e instalar a CLI 1. Abra [console.cloud.google.com](https://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](https://cloud.google.com/sdk/docs/install): 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_ID ``` ## Criar o banco de dados de produção Caminho para principiantes — Postgres gerido fora da Google. Em [supabase.com](https://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](https://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= in .env + apps/web/.env.local, then: corepack pnpm --filter @supastack/db db:migrate ``` ## Ativar 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:latest ``` ## Guardar 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_SECRET ``` ## Implementar 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. [Criar as contas mobile](https://supastack.dev/pt/docs/mobile/external-accounts.md) [Percorrer a lista de verificação de implementação completa](https://supastack.dev/pt/docs/web/deployment.md) Para continuar a configuração, leia [Checklist de deployment](https://supastack.dev/pt/docs/web/deployment.md). ## Seguinte [Checklist de deployment](https://supastack.dev/pt/docs/web/deployment.md)