Instalar Chatwoot em VPS: Guia de Automação Omnichannel

O Chatwoot é uma plataforma de código aberto para atendimento ao cliente que unifica mensagens de múltiplos canais (WhatsApp, Facebook, Instagram, Telegram, E-mail e Webchat) em um único painel. Para empresas que buscam controle total sobre seus dados, privacidade e personalização, a opção de instalar Chatwoot em uma VPS é a escolha ideal. Diferente de soluções SaaS padronizadas, hospedar sua própria instância permite configurar integrações específicas, manter a soberania dos dados dos clientes e evitar custos escaláveis por agente ou mensagem.

Neste tutorial técnico, guiaremos você pelo processo completo de provisionamento de um servidor de helpdesk self-hosted. Utilizaremos o método oficial via script de instalação (one-click install), que automatiza a configuração do stack necessário: Ruby on Rails para o backend, Vue.js para o frontend, PostgreSQL para o banco de dados e Redis para filas em tempo real. Este guia é essencial para profissionais de suporte técnico Linux e administradores de sistemas que desejam implementar uma solução robusta de automação de atendimento.

Pré-requisitos e Preparação do Ambiente

Antes de iniciar a instalação, é fundamental garantir que o ambiente esteja preparado. O Chatwoot possui requisitos de hardware específicos para operar com estabilidade, especialmente quando múltiplos canais estão ativos simultaneamente.

• Sistema Operacional: Ubuntu 20.04 LTS ou 22.04 LTS (recomendado).
• Especificações Mínimas: 2 vCPUs, 2GB de RAM e 20GB de disco SSD.
• Acesso Root: Você precisa ter acesso SSH com privilégios root ou um usuário com permissões sudo.
• Dominio: Um domínio registrado (ex: suporte.suaempresa.com) apontando para o IP da sua VPS. O Chatwoot exige HTTPS para funcionar corretamente, e o script de instalação configurará automaticamente certificados Let's Encrypt.

Caso ainda não tenha um servidor, provisione uma nova instância na sua provedora de cloud favorita. Certifique-se de que as portas 80 (HTTP) e 443 (HTTPS) estão abertas no firewall da VPS e nas regras de segurança do seu provedor.

Passo 1: Atualização do Sistema e Dependências Básicas

A primeira etapa é garantir que o sistema esteja atualizado e que todas as dependências básicas estejam instaladas. Abra seu terminal e conecte-se ao servidor via SSH:

ssh root@seu_ip_do_servidor

Execute os comandos abaixo para atualizar o índice dos pacotes e instalar ferramentas essenciais de gerenciamento e segurança:

apt update && apt upgrade -y
apt install curl wget gnupg2 ca-certificates apt-transport-https lsb-release -y

Essas ferramentas são necessárias para baixar os repositórios externos e gerenciar certificados SSL que serão configurados posteriormente.

Passo 2: Instalação do PostgreSQL

O Chatwoot utiliza o PostgreSQL como seu banco de dados principal. Embora o script de instalação tente lidar com isso, é uma boa prática de administração de sistemas ter o serviço configurado e pronto.

apt install postgresql postgresql-contrib -y

Inicie o serviço e garanta que ele esteja ativo na inicialização do sistema:

systemctl enable postgresql
systemctl start postgresql

O script oficial de instalação do Chatwoot cria automaticamente o banco de dados e o usuário necessários, mas manter o PostgreSQL atualizado evita problemas de compatibilidade.

Passo 3: Instalação do Redis

O Redis é utilizado pelo Chatwoot para armazenar sessões, cache e, principalmente, gerenciar as filas de processamento assíncrono (Sidekiq). Isso garante que o envio de mensagens em massa ou a integração com APIs externas não bloqueie a interface web.

apt install redis-server -y

Habilite e inicie o serviço:

systemctl enable redis-server
systemctl start redis-server

Passo 4: Execução do Script de Instalação Oficial

Agora chegamos ao núcleo da configuração. O Chatwoot oferece um script de instalação automatizado que baixa as dependências específicas (como Ruby e Node.js), configura o ambiente e realiza o deploy da aplicação. Este método é o mais seguro e recomendado para a maioria dos casos de uso, incluindo open source helpdesk deployments em produção.

Baixe e execute o script de instalação:

curl -sSL https://raw.githubusercontent.com/chatwoot/chatwoot/master/scripts/setup_v2.sh | bash

O script irá interagir com você durante o processo. Você será solicitado a fornecer as seguintes informações:

1. Dominio: Digite o domínio completo (ex: chat.suadominio.com). Não inclua http:// ou https://.
2. Email de Configuração: Um email válido para receber alertas do sistema e configurar o SMTP inicial.
3. Senha do Administrador: Defina uma senha forte para a conta admin padrão. Guarde esta senha, pois ela será sua chave mestra no helpdesk self-hosted.

O processo pode levar de 5 a 15 minutos, dependendo da velocidade da sua VPS e conexão de rede. O script irá:

• Instalar o Ruby e o Node.js nas versões compatíveis.
• Baixar o código fonte do Chatwoot.
• Configurar o PostgreSQL e o Redis.
• Gerar chaves criptográficas de segurança (secret key base).
• Executar as migrações do banco de dados.
• Compilar os assets estáticos (CSS/JS).

Aguarde até que a mensagem "Chatwoot installation completed successfully" seja exibida no terminal. Não interrompa o processo.

Passo 5: Configuração do Nginx e SSL

Após a instalação, o script configura automaticamente o Nginx como reverse proxy para a aplicação e solicita certificados SSL via Let's Encrypt (Certbot). No entanto, é crucial verificar se o serviço está rodando corretamente.

Verifique o status do serviço principal do Chatwoot:

systemctl status chatwoot.target

Você deve ver os serviços chatwoot-web, chatwoot-worker e chatwoot-cable (ActionCable) como "active (running)". Se algum estiver falhando, verifique os logs:

journalctl -u chatwoot-web -f

Se o acesso ao painel ainda não funcionar, reinicie o Nginx para garantir que as novas configurações de proxy estejam carregadas:

systemctl restart nginx

Acesse https://seu-dominio.com no navegador. Você deve ver a tela de login do Chatwoot.

Passo 6: Configuração Inicial e Segurança

Após fazer login com as credenciais criadas no passo 4, o primeiro passo é alterar a senha padrão e configurar o perfil da organização. Vá em Settings > Profile & Organization.

Configuração de E-mail (SMTP):

Para que o sistema envie notificações, respostas automáticas e recuperações de senha, você precisa configurar o SMTP. No menu lateral, vá em Settings > Account Settings > Email Channels ou configure globalmente nas configurações da conta.

# Exemplo de configuração no .env (se preferir edição manual futura)
# MAILER_INBOUND_EMAIL_DOMAIN=seu-dominio.com
# OUTGOING_EMAIL_ADDRESS=noreply@seu-dominio.com

Recomenda-se o uso de serviços como AWS SES, SendGrid ou Mailgun para garantir a entregabilidade dos e-mails.

Passo 7: Integração de Canais (Automação de Atendimento)

A grande vantagem do Chatwoot é a centralização. Vamos configurar o canal Webchat e um exemplo de integração com WhatsApp (via API ou parceiros).

1. Webchat:

Navegue até Settings > Channels > Webchat. Você verá um script JavaScript. Copie esse código e cole no cabeçalho (<head>) do seu site principal. O widget de chat aparecerá automaticamente para seus visitantes.

2. WhatsApp:

O Chatwoot não se conecta diretamente à API oficial do WhatsApp sem um parceiro Business Solution Provider (BSP). Para instalar Chatwoot VPS com WhatsApp funcional, você deve:

1. Cadastrar-se em plataformas como 360dialog, WATI ou Zoko.
2. Obter as credenciais de API (API Key e Phone Number ID).
3. Vá em Settings > Channels > WhatsApp.
4. Insira as chaves fornecidas pelo BSP.

Uma vez conectado, todas as conversas do WhatsApp fluirão para a caixa de entrada unificada do Chatwoot, permitindo que seus agentes respondam usando os mesmos templates e fluxos de trabalho do e-mail.

Passo 8: Manutenção e Backups

Um servidor de helpdesk self-hosted exige responsabilidade pela infraestrutura. Diferente de plataformas SaaS, onde o provedor faz backups automáticos, aqui a responsabilidade é sua.

Backup do Banco de Dados:

Crie um script cron para fazer backup diário do PostgreSQL:

# Edite o crontab
crontab -e

# Adicione a linha abaixo para backup diário às 3h da manhã
0 3 * * * pg_dump chatwoot_production | gzip > /backups/chatwoot_$(date +\%Y-\%m-\%d).sql.gz

Backup dos Arquivos:

Os arquivos anexados (imagens, PDFs) são armazenados localmente no diretório /var/www/chatwoot/public/system. Certifique-se de incluir esse diretório em sua estratégia de backup (ex: rsync para outro servidor ou upload para S3/MinIO).

Atualizações:

Para atualizar o Chatwoot, utilize o script oficial novamente. Ele tentará manter suas configurações e dados intactos, apenas atualizando as dependências e a estrutura do banco de dados.

curl -sSL https://raw.githubusercontent.com/chatwoot/chatwoot/master/scripts/setup_v2.sh | bash

Considerações Finais sobre Escalabilidade

A instalação padrão via script é perfeita para times de até 10-20 agentes e volumes moderados de mensagens. No entanto, à medida que o volume de tickets cresce, você pode precisar escalar a infraestrutura.

Para ambientes de alta disponibilidade, considere:

• Separar o banco de dados PostgreSQL para um servidor dedicado (RDS ou DBaaS).
• Utilizar um cluster Redis gerenciado.
• Configurar balanceamento de carga entre múltiplas instâncias do Chatwoot se a CPU estiver saturada durante picos de atendimento.

Ao instalar Chatwoot em uma VPS, você ganha flexibilidade total. Você pode personalizar o CSS, adicionar integrações via webhooks, criar bots personalizados com Ruby e ter controle granular sobre a segurança dos seus dados. Esta é a escolha definitiva para equipes que levam a experiência do cliente a sério e valorizam a autonomia tecnológica.

Com este guia, você estabeleceu as bases de um open source helpdesk profissional. Agora, foque em treinar sua equipe na utilização das ferramentas de automação, como macros, atribuição automática e inteligência artificial integrada (se disponível na versão), para maximizar a eficiência do seu time de suporte.