Typebot: Resolva Erros de Publicação e Webhooks em VPS

Entendendo os Problemas Comuns do Typebot em VPS

O Typebot é uma ferramenta excelente para criar chatbots interativos, mas como qualquer aplicação self-hosted, pode apresentar desafios na hora de colocá-lo em produção. Os problemas mais frequentes que meus clientes enfrentam incluem o typebot não publica o fluxo, erro ao salvar fluxo no typebot, typebot webhook não dispara e o build do typebot travando. Essas falhas geralmente indicam questões de configuração do ambiente, recursos insuficientes do VPS ou problemas com o proxy reverso. Rodar o Typebot de forma eficiente requer um ambiente bem configurado, idealmente em um VPS Linux com Docker. Para um ambiente de produção estável, recomendo um mínimo de 4GB de RAM e 2 vCPUs para o servidor completo rodando o Typebot junto com o PostgreSQL e um proxy reverso como Nginx.

Veja a infraestrutura: VPS para Evolution API no Brasil para colocar este projeto no ar.

Por Que o Typebot Não Publica o Fluxo?

O problema de "typebot não publica o fluxo" é um dos mais frustrantes. Geralmente, isso ocorre devido a erros no backend que impedem a gravação dos dados do fluxo no banco de dados, ou problemas de cache. Verifique os logs do contêiner do Typebot (principalmente o builder e o viewer) para mensagens de erro específicas. Conexão instável com o PostgreSQL ou credenciais incorretas no arquivo .env são causas comuns.

Causas de Erro ao Salvar Fluxo e Webhook Não Disparar

Um "erro ao salvar fluxo no typebot" pode indicar problemas de permissão no diretório de dados persistentes, falta de espaço em disco no VPS ou falha na comunicação com o banco de dados. Já o "typebot webhook não dispara" aponta para configurações incorretas do webhook (URL inválida, firewall bloqueando a saída, ou problemas de rede no lado do receptor do webhook), ou até mesmo um problema no worker do Typebot que processa essas requisições. A depuração dessas questões é crítica para a funcionalidade completa do seu chatbot.

Requisitos de Servidor para um Typebot Estável

Para evitar os problemas de performance e estabilidade que levam a erros de publicação e webhooks, é crucial dimensionar corretamente seu VPS. Muitos clientes subestimam a necessidade de recursos, o que leva a lentidão e falhas. Na minha experiência, um Typebot em produção com tráfego moderado, incluindo o banco de dados PostgreSQL e um proxy Nginx, exige recursos significativos.

Memória RAM e CPU Necessárias

Para um ambiente de produção, o Typebot, junto com o PostgreSQL e o proxy reverso, demanda pelo menos 4GB de RAM e 2 vCPUs. O Typebot em si, com seus diversos serviços (builder, viewer, editor, worker, etc.), pode consumir entre 1.5GB a 2.5GB de RAM em repouso, mas esse consumo pode aumentar sob carga. O PostgreSQL adiciona mais 512MB a 1GB, dependendo do volume de dados e conexões. Para testes e desenvolvimento, 2GB de RAM podem ser suficientes, mas não para um ambiente que precisa de alta disponibilidade e responsividade. Se você está vendo o build do typebot travando, a falta de memória ou CPU é um forte candidato.

Armazenamento e Rede

Para armazenamento, um SSD de 40GB a 60GB é o mínimo recomendado para o sistema operacional, Docker e dados do Typebot. Garanta que há espaço suficiente para os logs e para o crescimento do banco de dados. A largura de banda da rede também é um fator, especialmente se seu Typebot processa muitos webhooks ou interações. Um link de 100Mbps é geralmente adequado, mas para alto volume, considere um link de 1Gbps. Em diversos cenários, a escolha de um VPS robusto para agências pode ser a solução ideal para garantir que todos esses requisitos sejam atendidos sem surpresas.

Diagnóstico Avançado de Erros Comuns

Quando o Typebot apresenta comportamentos inesperados, como o typebot não publica o fluxo ou typebot webhook não dispara, a depuração eficaz é o seu melhor aliado. O primeiro passo é sempre verificar os logs dos contêineres.

Verificando Logs e Variáveis de Ambiente

Acesse seu VPS via SSH e utilize o comando docker compose logs -f para acompanhar o que está acontecendo em tempo real. Preste atenção aos contêineres builder, viewer e worker. Mensagens de erro como "database connection refused" ou "permission denied" são claras. Outro ponto crítico são as variáveis de ambiente no seu arquivo .env. Certifique-se de que DATABASE_URL, JWT_SECRET, NEXTAUTH_SECRET e quaisquer outras variáveis específicas para serviços externos (como S3 para armazenamento de arquivos) estejam configuradas corretamente. Um erro comum é esquecer de definir NEXT_PUBLIC_VIEWER_URL e NEXT_PUBLIC_EDITOR_URL, o que pode causar problemas de publicação e renderização de fluxos.

Problemas com Proxy Reverso e SSL

Se você estiver usando um proxy reverso (como Nginx ou Caddy), verifique suas configurações. Erros de SSL (certificado expirado ou configuração incorreta) podem impedir o acesso ao Typebot, e regras de proxy mal configuradas podem bloquear a comunicação entre o frontend e o backend, ou impedir que os webhooks externos cheguem ao seu servidor. Assegure-se de que as portas corretas (geralmente 80 e 443) estejam abertas no firewall do seu VPS e que o proxy reverso esteja encaminhando o tráfego para a porta interna do Typebot (normalmente 3000 ou 3001, dependendo do serviço). Para uma análise mais aprofundada de problemas de deploy e webhook, recomendo a leitura do nosso artigo sobre Typebot: Resolva Problemas de Deploy e Webhook.

Passo a Passo: Deploy do Typebot em VPS com Docker Compose

Este guia prático mostra como configurar o Typebot em um VPS Ubuntu, utilizando Docker Compose para uma instalação robusta e fácil de gerenciar. Assumimos que você já tem um VPS com Ubuntu 22.04 ou superior, com Docker e Docker Compose instalados.

1. Preparação do Ambiente e Variáveis de Ambiente

Primeiro, crie um diretório para o Typebot e navegue até ele. Em seguida, crie o arquivo .env com suas variáveis de ambiente. É crucial substituir os valores entre <> por informações reais e seguras.

sudo apt update && sudo apt upgrade -y
sudo apt install -y docker.io docker-compose-plugin

mkdir typebot && cd typebot

sudo nano .env

Conteúdo do arquivo .env:

DATABASE_URL="postgresql://typebot:SUA_SENHA_POSTGRES@db:5432/typebot?schema=public"
NEXTAUTH_SECRET="GERAR_CHAVE_COMPLEXA_AQUI"
JWT_SECRET="GERAR_OUTRA_CHAVE_COMPLEXA_AQUI"
NEXT_PUBLIC_VIEWER_URL="https://seu_dominio.com"
NEXT_PUBLIC_EDITOR_URL="https://app.seu_dominio.com"
ADMIN_EMAIL="[email protected]"
# Opcional: para armazenamento de arquivos (S3 ou compatível)
# S3_ACCESS_KEY="SEU_S3_ACCESS_KEY"
# S3_SECRET_KEY="SEU_S3_SECRET_KEY"
# S3_ENDPOINT="https://s3.seu_provedor.com"
# S3_BUCKET="seu-bucket-typebot"
# S3_PORT="443"
# S3_SSL_ENABLED="true"

Dica de insider: Use geradores de senhas online para NEXTAUTH_SECRET e JWT_SECRET. Chaves fracas são um risco de segurança e podem levar a comportamentos inesperados do Typebot.

2. Criação do Arquivo docker-compose.yml

Este é o coração do seu deploy. Crie o arquivo docker-compose.yml no mesmo diretório do .env:

version: '3.8'

services:
  db:
    image: postgres:15-alpine
    restart: always
    environment:
      POSTGRES_USER: typebot
      POSTGRES_PASSWORD: ${SUA_SENHA_POSTGRES}
      POSTGRES_DB: typebot
    volumes:
      - db_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U typebot -d typebot"]
      interval: 5s
      timeout: 5s
      retries: 5

  builder:
    image: typebot/builder:latest
    restart: always
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
      - JWT_SECRET=${JWT_SECRET}
      - NEXT_PUBLIC_VIEWER_URL=${NEXT_PUBLIC_VIEWER_URL}
      - NEXT_PUBLIC_EDITOR_URL=${NEXT_PUBLIC_EDITOR_URL}
      - ADMIN_EMAIL=${ADMIN_EMAIL}
      # S3_ACCESS_KEY: ${S3_ACCESS_KEY}
      # S3_SECRET_KEY: ${S3_SECRET_KEY}
      # S3_ENDPOINT: ${S3_ENDPOINT}
      # S3_BUCKET: ${S3_BUCKET}
      # S3_PORT: ${S3_PORT}
      # S3_SSL_ENABLED: ${S3_SSL_ENABLED}
    ports:
      - "3000:3000"
    depends_on:
      db:
        condition: service_healthy

  viewer:
    image: typebot/viewer:latest
    restart: always
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - JWT_SECRET=${JWT_SECRET}
      - NEXT_PUBLIC_VIEWER_URL=${NEXT_PUBLIC_VIEWER_URL}
    ports:
      - "3001:3000"
    depends_on:
      db:
        condition: service_healthy

volumes:
  db_data:

3. Subindo os Contêineres e Configurando o Proxy Reverso

Após criar os arquivos, suba os serviços com Docker Compose. O Typebot pode demorar alguns minutos para inicializar completamente na primeira vez.

sudo docker compose up -d

sudo docker compose logs -f

Para acessar seu Typebot via um nome de domínio (ex: app.seu_dominio.com para o builder/editor e seu_dominio.com para o viewer), você precisará configurar um proxy reverso (Nginx ou Caddy). Abaixo está um exemplo de configuração Nginx para o builder. Adapte para o viewer e para seu domínio.

server {
    listen 80;
    server_name app.seu_dominio.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

server {
    listen 80;
    server_name seu_dominio.com;

    location / {
        proxy_pass http://localhost:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Lembre-se de instalar o Nginx (sudo apt install nginx) e ativar o site após criar o arquivo de configuração em /etc/nginx/sites-available/seu_dominio e criar um link simbólico para /etc/nginx/sites-enabled/. Não se esqueça de configurar o SSL com Certbot (sudo certbot --nginx -d app.seu_dominio.com -d seu_dominio.com) para garantir a segurança da sua aplicação.

Erros Comuns e Como Evitá-los no Typebot

A experiência com Typebot self-hosted pode ser desafiadora, mas muitos problemas são recorrentes e podem ser prevenidos com as práticas corretas.

Falta de Recursos e OOM Killer

Um dos problemas mais comuns é a falta de memória RAM, que leva o kernel Linux a ativar o "Out Of Memory Killer" (OOM Killer), encerrando processos aleatoriamente para liberar memória. Isso pode fazer com que o build do typebot trave, o banco de dados pare, ou o Typebot não consiga publicar fluxos. Certifique-se de que seu VPS tenha memória suficiente (mínimo de 4GB para produção). Monitore o uso de RAM com htop ou docker stats regularmente.

Configurações Incorretas de Banco de Dados e Variáveis

Um erro simples na DATABASE_URL no arquivo .env pode impedir o Typebot de se conectar ao PostgreSQL, resultando em "erro ao salvar fluxo no typebot" e falhas na publicação. Verifique triplamente as credenciais, o nome do host (db no nosso exemplo de Docker Compose) e a porta. Além disso, variáveis como NEXT_PUBLIC_VIEWER_URL e NEXT_PUBLIC_EDITOR_URL são cruciais para que o Typebot gere os links corretos para seus fluxos e para que o editor funcione adequadamente.

Problemas de Rede e Firewall

Se o typebot webhook não dispara, a causa pode estar no firewall do VPS (UFW ou iptables) bloqueando as requisições de saída do Typebot ou as requisições de entrada dos serviços externos. Verifique se as portas 80 e 443 estão abertas para o tráfego HTTP/HTTPS. Além disso, assegure-se de que o servidor do webhook externo não esteja bloqueando as requisições vindas do IP do seu VPS. Em alguns casos, serviços como a Evolution API podem ter listas de IP permitidas, e seu VPS precisa estar nessa lista.

Aqui está uma tabela comparando algumas opções de deploy para o Typebot:

Perguntas Relacionadas

Como posso otimizar o desempenho do meu Typebot em produção?

Para otimizar o desempenho, garanta que seu VPS tenha memória e CPU adequadas (mínimo 4GB RAM, 2 vCPUs). Utilize um banco de dados PostgreSQL performático e otimize suas consultas se houver problemas. Implemente um proxy reverso como Nginx ou Caddy com cache para servir recursos estáticos mais rapidamente e configure o SSL para segurança. Monitore constantemente os logs e o uso de recursos para identificar gargalos.

Qual a melhor forma de fazer backup do meu Typebot self-hosted?

A melhor forma de fazer backup é criar rotinas diárias ou semanais para o volume de dados do PostgreSQL. Você pode usar ferramentas como pg_dump para exportar o banco de dados e copiar os arquivos para um armazenamento externo seguro (S3, Google Cloud Storage, etc.). Certifique-se de também fazer backup do seu arquivo .env e do docker-compose.yml.

Posso usar um serviço de banco de dados externo com o Typebot?

Sim, você pode configurar o Typebot para usar um serviço de banco de dados PostgreSQL gerenciado (como o da AWS RDS ou DigitalOcean Managed Databases). Isso delega a manutenção do banco de dados ao provedor, liberando recursos do seu VPS. Basta ajustar a DATABASE_URL no seu arquivo .env para apontar para o endpoint do seu serviço de banco de dados externo.

O que fazer se o Typebot não carrega o editor ou o viewer?

Se o editor ou viewer não carregam, verifique primeiro os logs do contêiner builder e viewer. Erros de JavaScript no console do navegador (F12) também são importantes. Assegure-se de que NEXT_PUBLIC_VIEWER_URL e NEXT_PUBLIC_EDITOR_URL no seu .env estejam configurados com os domínios corretos e que o proxy reverso esteja encaminhando o tráfego adequadamente para as portas 3000 e 3001.

Garanta a Estabilidade do seu Typebot com um VPS Host You Secure

Evitar que o typebot não publica o fluxo, erro ao salvar fluxo no typebot, ou que o typebot webhook não dispara exige um ambiente de hospedagem confiável e dimensionado corretamente. Um VPS robusto é a base para o sucesso do seu Typebot self-hosted. Com a Host You Secure, você tem a infraestrutura ideal para rodar suas aplicações críticas sem preocupações.

Para garantir que seu Typebot opere com máxima performance e estabilidade, recomendamos o VPS Brasil Básico. Com 4GB de RAM e 4 vCPUs, este plano oferece os recursos necessários para um Typebot em produção, incluindo PostgreSQL e proxy reverso, por apenas R$ 99/mês. Temos esse mesmo stack em produção em uma VPS Brasil Básico, garantindo a performance e a resiliência que seus chatbots precisam. Não deixe que problemas de infraestrutura comprometam seus projetos.

Clique aqui para contratar seu VPS Brasil Básico e hospedar seu Typebot com confiança!