Guia de configuracao

1. Instalar e criar o acesso

1. Instale Node.js 24 e obtenha uma copia limpa do codigo.
2. Na pasta do projeto, execute os comandos abaixo.
3. Abra o endereco local mostrado no terminal e defina a senha inicial do administrador. O primeiro usuario da base nova e admin@local.test; ele nao vem com senha pronta.
4. Em Perfil, ajuste os dados do administrador. Crie os funcionarios em Usuarios e confira suas permissoes.

npm ci
npm run setup
npm start

O setup cria um arquivo .env com chave exclusiva. Nao sobrescreve um arquivo existente. O painel fica restrito ao computador local por padrao.

Para uso remoto, mantenha o aplicativo atras de um proxy HTTPS e configure PUBLIC_PANEL_URL. Conclua o acesso inicial antes de liberar a rede. Publicar paginas na Cloudflare nao hospeda automaticamente o proprio painel.

2. Preparar a Cloudflare

Nao e somente colar um token: voce precisa do Account ID, de um token da mesma conta e das zonas/dominos que pretende usar.

1. Na Cloudflare, configure o subdominio workers.dev em Workers & Pages. Copie o Account ID, com 32 caracteres hexadecimais. Ele e diferente do Zone ID.
2. Adicione seu dominio a essa conta e configure no registrador exatamente os nameservers indicados pela Cloudflare. Aguarde o status Active.
3. Crie um API Token personalizado, limitado a sua conta e as suas zonas. Use as permissoes abaixo; nao use Global API Key.
4. No painel, abra Dominios, cadastre o nome da conta, Account ID e API Token. O subdominio Workers e detectado automaticamente. Nenhum login global do Wrangler e necessario.
5. Sincronize os dominios e confira os disponiveis. Um dominio ativo na Cloudflare ainda pode estar fora da rotacao por limite de uso, pausa ou reserva do administrador.

Os nomes Edit e Write podem variar conforme a interface. Restrinja os recursos e, se utilizar filtro de IP no token, permita o IP de saida do servidor que executa o painel. O token precisa permitir tambem limpar os recursos criados no teste.

Dominios .com, .com.br e .lat seguem as regras regulares. .shop e reservado ao administrador. Na VPS AD Scale, o timer adscale-domain-sync verifica todas as contas cadastradas cinco minutos após o ciclo anterior, mesmo com o navegador fechado. A rotina acompanha a ativação dos domínios e prepara o recebimento de e-mails nas zonas elegíveis. Sem contas cadastradas, aguarda o próximo ciclo.

Fontes: permissoes de Workers e permissoes de tokens.

3. Confirmar que publica

1. Testar conexao verifica acesso de leitura. Nao comprova escrita nem pagina no ar.
2. Testar publicacao cria um Worker tecnico temporario, sem dados de empresas. Se houver zona ativa na conta, testa tambem dominio proprio e escrita DNS com um TXT temporario.
3. O teste somente aprova se a pagina publica responder HTTP 200 e contiver a metatag tecnica esperada. Depois remove apenas os recursos temporarios que criou.
4. Sem zona ativa, a verificacao ocorre em workers.dev; o resultado deixa claro que dominio proprio e DNS nao foram testados.

O teste usa a cota da conta Cloudflare e pode levar alguns minutos. Se a limpeza ficar pendente, a mensagem identifica o Worker temporario. Remova somente esse recurso, nunca sites dos clientes para tentar corrigir uma falha.

Um teste aprovado comprova aquele momento e ambiente. Propagacao, limites de plano, vencimento do token ou indisponibilidade do provedor podem afetar publicacoes futuras. O sistema nao deve marcar erro de entrega como sucesso.

4. Criar e publicar o primeiro site

1. Para buscar empresas automaticamente, entre como ADM e salve sua chave em Integrações → Casa dos Dados. A chave salva no painel tem prioridade sobre CASA_DADOS_API_KEY do ambiente. A consulta de CNPJ pode consumir créditos.
2. Entre como administrador, sincronize suas zonas e confira as permissoes de publicacao, projetos e usuarios.
3. Em Criar site, consulte o CNPJ e revise nome legal, contato e endereco da empresa. Nao invente dados nem use o numero estadual como se fosse um identificador fiscal diferente.
4. Confira o dominio final. Por padrao, o subdominio usa o primeiro nome da empresa; voce pode editar antes da publicacao.
5. Copie o dominio, obtenha a metatag da propria empresa e cole-a no campo correspondente. Nao troque o dominio depois de gerar a tag sem revisar a verificacao.
6. Publique e aguarde a confirmacao do conteudo publico. Acesse o endereco final e confira os dados e a metatag no codigo da pagina.

A metatag no site nao significa aprovacao cadastral da empresa por terceiros. O dominio raiz admite apenas uma publicacao por endereco; prefira subdominios quando houver varias empresas.

Rotacao

O limite padrao da copia e 12 sites por dominio, configuravel no ambiente. Pausar ou retirar um dominio da rotacao nao deve apagar os sites existentes. Nao foram incluidos os dominios, reservas ou excecoes da instalacao anterior.

5. E-mail e SMS sao opcionais

Para Email Routing, acrescente Account / Email Routing Addresses / Edit, Zone / Email Routing Rules / Edit e Zone / Zone Settings / Edit, alem das permissoes DNS. Configure o endereco publico HTTPS do painel e, se desejar encaminhar, um destino de e-mail verificado.

O recebimento no painel depende de ele estar acessivel pela Internet; localhost nao recebe webhooks da Cloudflare. Nao substitua registros MX de outro provedor sem revisar o servico de e-mail existente. Teste o recebimento com uma mensagem comum antes de depender dele para codigos.

SMS exige uma conta e chave proprias de um provedor suportado, saldo e permissao dos usuarios. Teste a configuracao antes de comprar numeros. Nenhum saldo, mensagem, numero ou chave da operacao anterior e transferido nesta copia.

6. Antes de compartilhar ou colocar na Internet

• Nunca envie .env, configuracao PM2 real, bancos, sessoes, logs, mensagens, pastas de publicacao ou backups junto do codigo.
• Uma nova operacao deve iniciar com banco vazio, chave propria e contas proprias. Para restaurar um backup existente, preserve a chave original que o criptografou.
• A variavel de ambiente BLOCKED_PUBLISHING_DOMAINS recebe sua propria lista, separada por virgulas. Nao copie listas particulares de outra operacao.
• Use HTTPS, firewall, senhas fortes e usuarios separados. Nao exponha a porta interna do Node desnecessariamente.
• Guarde backup privado do banco, da configuracao e dos estados de rotacao. O Git nao e backup dos dados da operacao.
• Valide os direitos de uso de imagens, fontes e outros recursos antes de redistribuir comercialmente a copia.