Como instalar o Chatwoot em uma VPS Ubuntu

O Chatwoot é uma plataforma open-source de atendimento ao cliente com suporte a WhatsApp, e-mail, chat web e muito mais. Este guia usa a instalação via Docker Compose com PostgreSQL e Redis — o método oficial recomendado para ambientes Docker.

Instalação passo a passo

1. 1

   Atualizar o sistema e instalar Docker

   Garanta que Docker e Docker Compose estão instalados.

   bashCopiar

   apt update && apt upgrade -y
   curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh
   docker --version && docker compose version

2. 2

   Criar o diretório do projeto

   Crie a pasta de trabalho para o Chatwoot.

   bashCopiar

   mkdir -p /opt/chatwoot
   cd /opt/chatwoot

3. 3

   Baixar o arquivo de variáveis de ambiente oficial

   O Chatwoot disponibiliza um .env.example no repositório oficial.

   bashCopiar

   curl -L https://raw.githubusercontent.com/chatwoot/chatwoot/develop/.env.example -o .env

4. 4

   Configurar variáveis essenciais no .env

   Edite as variáveis obrigatórias para o ambiente de produção.

   .env (trecho)Copiar

   # Variáveis obrigatórias a alterar em /opt/chatwoot/.env
   
   # URL pública do Chatwoot
   FRONTEND_URL=https://chat.seudominio.com.br
   
   # Banco de dados
   POSTGRES_HOST=postgres
   POSTGRES_USERNAME=postgres
   POSTGRES_PASSWORD=troque_por_senha_forte_aqui
   POSTGRES_DATABASE=chatwoot
   
   # Redis
   REDIS_URL=redis://:SENHA_REDIS@redis:6379
   REDIS_PASSWORD=troque_por_senha_redis_aqui
   
   # Segredo Rails
   SECRET_KEY_BASE=$(openssl rand -hex 64)
   
   # E-mail (configurar para envio de notificações)
   MAILER_SENDER_EMAIL=noreply@seudominio.com.br

   Atenção

   Gere um SECRET_KEY_BASE real com `openssl rand -hex 64`. Não use valores de exemplo em produção. Configure também as variáveis de SMTP para envio de e-mails.
5. 5

   Criar o docker-compose.yml

   Esta configuração inclui Rails (aplicação), Sidekiq (filas), PostgreSQL e Redis.

   docker-compose.ymlCopiar

   # /opt/chatwoot/docker-compose.yml
   services:
     base: &base
       image: chatwoot/chatwoot:latest
       env_file: .env
       volumes:
         - storage_data:/app/storage
   
     rails:
       <<: *base
       depends_on:
         - postgres
         - redis
       ports:
         - "127.0.0.1:3000:3000"
       environment:
         - NODE_ENV=production
         - RAILS_ENV=production
         - INSTALLATION_ENV=docker
       entrypoint: docker/entrypoints/rails.sh
       command: ["bundle", "exec", "rails", "s", "-p", "3000", "-b", "0.0.0.0"]
       restart: always
   
     sidekiq:
       <<: *base
       depends_on:
         - postgres
         - redis
       environment:
         - NODE_ENV=production
         - RAILS_ENV=production
         - INSTALLATION_ENV=docker
       command: ["bundle", "exec", "sidekiq", "-C", "config/sidekiq.yml"]
       restart: always
   
     postgres:
       image: pgvector/pgvector:pg16
       restart: always
       volumes:
         - postgres_data:/var/lib/postgresql/data
       environment:
         - POSTGRES_DB=chatwoot
         - POSTGRES_USER=postgres
         - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
   
     redis:
       image: redis:alpine
       restart: always
       command: ["sh", "-c", "redis-server --requirepass "$REDIS_PASSWORD""]
       env_file: .env
       volumes:
         - redis_data:/data
   
   volumes:
     storage_data:
     postgres_data:
     redis_data:

6. 6

   Preparar o banco de dados

   Antes de subir todos os serviços, execute as migrações do banco.

   bashCopiar

   cd /opt/chatwoot
   
   # Subir apenas o banco e o Redis primeiro
   docker compose up -d postgres redis
   
   # Aguardar o PostgreSQL inicializar (~15s)
   sleep 15
   
   # Executar migrações e seed
   docker compose run --rm rails bundle exec rails db:chatwoot_prepare

   Dica

   O comando `db:chatwoot_prepare` cria o banco, aplica migrações e insere dados iniciais. Pode levar 1-2 minutos.
7. 7

   Subir todos os serviços

   Após as migrações, suba a aplicação completa.

   bashCopiar

   cd /opt/chatwoot
   docker compose up -d
   
   # Verificar todos os containers
   docker compose ps
   
   # Acompanhar logs do Rails
   docker compose logs rails --follow

8. 8

   Configurar Nginx e SSL

   Configure o reverse proxy e emita certificado SSL.

   bashCopiar

   apt install -y nginx certbot python3-certbot-nginx
   
   cat > /etc/nginx/sites-available/chatwoot << 'NGINXEOF'
   server {
       listen 80;
       server_name chat.seudominio.com.br;
       return 301 https://$host$request_uri;
   }
   
   server {
       listen 443 ssl;
       server_name chat.seudominio.com.br;
   
       ssl_certificate /etc/letsencrypt/live/chat.seudominio.com.br/fullchain.pem;
       ssl_certificate_key /etc/letsencrypt/live/chat.seudominio.com.br/privkey.pem;
   
       client_max_body_size 100M;
   
       location / {
           proxy_pass http://127.0.0.1:3000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           proxy_read_timeout 3600s;
       }
   }
   NGINXEOF
   
   ln -s /etc/nginx/sites-available/chatwoot /etc/nginx/sites-enabled/chatwoot
   nginx -t
   
   certbot --nginx \
     -d chat.seudominio.com.br \
     --non-interactive \
     --agree-tos \
     --email seu@email.com
   
   systemctl reload nginx

   Atenção

   Substitua chat.seudominio.com.br pelo seu subdomínio real. O FRONTEND_URL no .env deve corresponder a este endereço.
9. 9

   Configurar firewall e criar conta de superadmin

   Libere as portas necessárias e crie o primeiro usuário administrador.

   bashCopiar

   ufw allow 22/tcp && ufw allow 80/tcp && ufw allow 443/tcp
   ufw --force enable
   
   # Criar superadmin via console Rails
   docker compose exec rails bundle exec rails c
   # No console Rails, execute:
   # SuperAdmin.create!(email: 'admin@seudominio.com.br', password: 'senha_forte', password_confirmation: 'senha_forte')
   # exit

   Dica

   Alternativamente, acesse https://chat.seudominio.com.br e crie a conta pelo formulário de registro inicial.

Troubleshooting

Perguntas frequentes