Implante o app do Chatfuel wizard: Vercel, Node.js ou Docker

O app que o Chatfuel wizard escreve roda na Vercel, no seu próprio servidor Node.js ou no Docker, a partir do mesmo código. O host decide quem gerencia o TLS e quanto tempo um WebSocket fica aberto; ele não decide quem pode usar o app. Essa segunda questão vem primeiro, porque o app fala com o Chatfuel usando o seu token de API pessoal: quem acessa o app age com o acesso desse token, a menos que o módulo auth peça para a pessoa fazer login.

Como implantar na Vercel

O wizard oferece uma implantação na Vercel no fim da execução. Depois, execute-a a partir do diretório do app:

npm run deploy

O script de implantação (scripts/deploy-vercel.mjs no seu app) usa a Vercel CLI: ele verifica se você fez login, vincula o projeto, envia as variáveis do seu .env para o projeto na Vercel, faz a implantação e pergunta à nova implantação se ela subiu configurada. O seu arquivo .env local nunca é enviado; as variáveis ficam no projeto da Vercel.

• Requisições: o proxy roda como uma função da Vercel atrás de um rewrite de /chatfuel/*.
• Atualizações ao vivo: um WebSocket dura o tempo máximo de execução da função, e então o app se reconecta sozinho.
• Caminho: o app é servido a partir da raiz do domínio; um subcaminho como /app/ precisa de um servidor Node.js ou do Docker.

Como executar o app no seu próprio servidor Node.js

npm run build && npm start

npm run build gera o build do app de navegador e do servidor. npm start executa um único servidor Node.js que serve o app compilado e o proxy /chatfuel/* na porta 3000 (defina PORT para mudá-la e HOST para escolher a interface). Coloque na frente dele um proxy reverso com TLS, como nginx ou Caddy.

Como executar o app no Docker

O app vem com um Dockerfile que gera o build do app e inicia o mesmo servidor Node.js na porta 3000. Passe os valores públicos VITE_* como argumentos de build e todos os segredos em tempo de execução, por exemplo com docker run --env-file .env. Nunca passe CHATFUEL_TOKEN nem outro segredo como argumento de build: os argumentos de build continuam legíveis na imagem.

Quem pode acessar o app implantado

Sem o módulo auth, o app não tem login: o proxy encaminha toda requisição que recebe com o seu token de API pessoal. Qualquer pessoa que abrir a URL pode ler conversas e contatos, enviar mensagens como o bot e alterar configurações, mesmo que o próprio token nunca saia do servidor. Essa configuração serve para uma ferramenta da sua própria equipe, mantida fora da internet pública:

• em uma VPN, em uma rede Tailscale ou WireGuard, ou atrás de uma lista de IPs permitidos do escritório;
• atrás do controle de acesso do seu host, como Vercel Deployment Protection, auth_basic do nginx ou Cloudflare Access;
• apenas em localhost, que é o que npm run dev oferece.

Um app que clientes ou funcionários abrem pela internet precisa do módulo auth: cada pessoa faz login com o seu projeto do Supabase antes que o proxy encaminhe qualquer coisa. Adicione-o com npx @chatfuel/wizard --embed. Módulos do wizard descreve o auth.

Quais configurações o servidor se recusa a executar

O servidor recusa duas configurações em vez de apenas avisar sobre elas. npm start mostra REFUSING TO SERVE e não inicia, o servidor de desenvolvimento do Vite com --host para antes de montar o proxy, e a função da Vercel responde 503 com o código ProxyRefusedToServe a tudo, exceto à verificação de saúde.

• Sem login em um host que não é loopback. Por padrão, o servidor escuta em todas as interfaces e, sem auth, qualquer pessoa que consiga alcançá-lo usa o seu token. Corrija de uma de três formas: instale o módulo auth, vincule o servidor ao loopback com HOST=127.0.0.1 ou, quando algo na frente do app já autentica cada visitante, defina CHATFUEL_OPEN_PROXY=1 para confirmar que a configuração aberta é intencional.
• ALLOWED_ORIGINS=* em um host que não é loopback, com ou sem login. Defina ALLOWED_ORIGINS com as origens que servem o app, separadas por vírgulas, por exemplo https://app.example.com. CHATFUEL_OPEN_PROXY não cobre esse caso.

Como verificar uma implantação e proteger o painel de administração

/chatfuel/healthz responde em todos os hosts. Ele retorna {"ok":true} com status 200 quando o servidor está configurado, ou {"ok":false} com 503 quando a configuração tem um problema. Uma página HTML como resposta significa que o caminho está errado.

O módulo admin adiciona um painel em /admin que pode alterar toda a conta por trás do token. ADMIN_PASSWORD é a única proteção dele e precisa ter pelo menos 16 caracteres, ou o painel se recusa a rodar. Com o módulo auth instalado, defina também SUPABASE_SERVICE_ROLE_KEY para que todas as instâncias do servidor compartilhem uma única contagem de senhas erradas; na Vercel, onde qualquer instância ativa pode responder, a contagem fica, caso contrário, separada em cada instância.

Regras que todo host precisa seguir

• Caminhos desconhecidos respondem com index.html. Cada tela tem um endereço real, como /deals, e recarregar a página precisa voltar a ela. O servidor Node.js e o vercel.json incluído já fazem isso; no nginx, use try_files $uri /index.html;.
• As variáveis VITE_* são fixadas no momento do build; todas as outras variáveis são lidas pelo servidor em tempo de execução. Depois de mudar um valor VITE_*, gere o build de novo. Um app de navegador compilado com as configurações do Supabase e um servidor iniciado sem elas, ou o contrário, falham no login com ProxyAuthMisconfigured ou AuthSessionRequired.
• Os segredos ficam no servidor. Nada com nome VITE_* pode guardar um segredo, porque esses valores são compilados no código do navegador.

Problemas comuns

REFUSING TO SERVE: open mode on a host that is not loopback

O servidor roda sem o módulo auth em um endereço que outras pessoas conseguem alcançar. Instale o auth, defina HOST=127.0.0.1 ou defina CHATFUEL_OPEN_PROXY=1 quando o seu próprio controle de acesso já estiver na frente do app.

REFUSING TO SERVE: ALLOWED_ORIGINS is '*'

Substitua * pelas origens exatas do seu app, por exemplo ALLOWED_ORIGINS=https://app.example.com, e reinicie o servidor.

ADMIN_PASSWORD must be at least 16 characters. Set a longer one and restart.

O painel de administração recusa uma senha curta. Defina uma ADMIN_PASSWORD mais longa no ambiente do servidor, ou no projeto da Vercel, e reinicie o servidor ou implante de novo.