Configurar domínios personalizados

Instalação e configuração

Antes de qualquer etapa, leia Antes de começar e Noções básicas sobre terminal. Estas instruções presumem que você abriu o monorepo supastack completo no VS Code; sua raiz package.json marca a raiz do repositório. Nos comandos pnpm, um pacote de espaço de trabalho é um aplicativo ou uma pasta de código compartilhado; no produto, um espaço de trabalho é o contêiner de dados e o limite de segurança de uma equipe. corepack pnpm --filter ... seleciona um pacote do monorepo enquanto os comandos são executados a partir de sua raiz. Se você abriu apenas uma pasta móvel ou desktop sincronizada, ela não contém o back-end da Web, a configuração do Docker ou os scripts raiz: execute o back-end deste monorepo ou de um servidor hospedado acessível e use os próprios scripts da pasta da plataforma. Uma variável de ambiente é uma configuração nomeada armazenada em um arquivo .env local ou no painel de hospedagem; reinicie o aplicativo relevante após alterá-lo e mantenha os segredos do servidor fora dos valores NEXT_PUBLIC_ e EXPO_PUBLIC_.

1. Abra apps/web/.env.local e use CUSTOM_DOMAINS_PROVIDER=local para visualizar a tela Domínios sem alterações em DNS.

2. Para obter um nome de host de cliente real, configure o Cloudflare for SaaS com sua própria zona, um token API limitado a essa zona e o destino CNAME; insira os valores somente do servidor no host da Web, não no navegador.

3. Execute a Web com corepack pnpm --filter @supastack/web dev e abra Configurações → Domínios como proprietário/administrador do espaço de trabalho. Esperado: o adaptador local ativa um domínio de teste imediatamente; o adaptador Cloudflare aguarda os registros DNS exibidos.

Defina CUSTOM_DOMAINS_PROVIDER=cloudflare com CLOUDFLARE_API_TOKEN, CLOUDFLARE_ZONE_ID e CUSTOM_DOMAIN_CNAME_TARGET. O token API precisa da permissão SSL e Certificados:Editar na zona (os nomes de host personalizados API ficam em /zones/{zone_id}/custom_hostnames). O destino CNAME é um nome de host na sua zona Cloudflare — por exemplo, clients.example.com — que é resolvido para seu aplicativo implantado.

Adicione um registro DNS na zona apontando o destino CNAME para sua origem (a origem substituta nos termos do Cloudflare para SaaS). A Cloudflare emite para cada nome de host personalizado um registro DCV TXT mais um registro de propriedade opcional TXT; a tela de configurações mostra aos clientes exatamente quais registros criar.

Para desenvolvimento local, use CUSTOM_DOMAINS_PROVIDER=local, que marca cada nome de host ativo imediatamente com clientes alvo.localhost. CUSTOM_DOMAINS_PROVIDER=off (o padrão) oculta os controles da seção.

CUSTOM_DOMAINS_PROVIDER=cloudflare
CLOUDFLARE_API_TOKEN=cf_token_with_ssl_edit
CLOUDFLARE_ZONE_ID=zone_id
CUSTOM_DOMAIN_CNAME_TARGET=customers.example.com

Comandos para copiar

Siga os comentários para ver em qual pasta um comando é executado. Se dois terminais estiverem rotulados, abra duas janelas de terminal e mantenha o primeiro comando em execução enquanto usa o segundo.

corepack pnpm --filter @supastack/web dev

Fluxo de implementação

Proprietários e administradores de workspaces gerenciam domínios em Configurações → Domínios (cinco por workspace). Os clientes apontam um registro CNAME para seu nome de host no destino CNAME, adicionam os registros TXT mostrados para propriedade e validação de certificado e, em seguida, pressionam Atualizar status. Depois que a Cloudflare relata o nome do host ativo, ele se torna uma origem confiável para autenticação nessa implantação e o nome/logotipo do espaço de trabalho marca o cromo do aplicativo nesse nome de host.

Os domínios Apex (raiz) não podem ser CNAMEs na maioria dos provedores DNS — os clientes devem usar um subdomínio como portal.example.com ou um provedor com nivelamento CNAME. Os cookies permanecem no escopo de cada host, portanto, um domínio de cliente é um login separado; o logon único em domínios personalizados está fora do escopo.

Verificação e resolução de problemas

Se a Cloudflare permanecer pendente, compare os registros CNAME e TXT do cliente com os valores exatos mostrados no cartão de domínio e aguarde a atualização do DNS. Use um subdomínio quando o provedor DNS não puder nivelar um domínio raiz CNAME. Se o menu estiver ausente, verifique se o recurso está habilitado e se o usuário conectado é proprietário ou administrador do workspace.

Pendente por um longo período geralmente significa que o CNAME do cliente está ausente ou ainda em propagação – verifique novamente os registros DNS mostrados no cartão de domínio. Um status movido ou com falha significa que a Cloudflare não pode mais resolver o nome do host para a zona; remova e adicione novamente. Os dados de validação são armazenados como provedor JSON, portanto, os formatos de validação futuros da Cloudflare não precisam de alteração de esquema.