O mercado de gestão de relacionamento com o cliente (CRM) e planejamento de recursos empresariais (ERP) vive uma transformação digital acelerada. Embora soluções como Salesforce dominem o cenário corporativo global, elas frequentemente impõem custos de licença elevados, complexidade na integração e a necessidade de manter dados sensíveis em nuvens públicas de terceiros. Para empresas brasileiras que buscam soberania de dados, controle total da infraestrutura e redução de custos operacionais, a alternativa mais robusta é o twentycrm self-hosted. Esta abordagem permite instalar um CRM moderno no seu próprio ambiente, seja ele uma VPS ou servidor dedicado, garantindo flexibilidade e personalização sem as limitações de plataformas SaaS proprietárias.
O TwentoCRM surge como uma resposta direta à necessidade de ferramentas open source que não pareçam遗留 sistemas dos anos 20. Diferente do SuiteCRM, que carrega a herança complexa do SugarCRM, ou do EspoCRM, que prioriza leveza em detrimento de interfaces mais ricas, o TwentoCRM oferece uma experiência de usuário contemporânea, construída com tecnologias modernas como Next.js e Prisma. Neste tutorial técnico, detalhamos o processo completo de instalação e configuração do TwentoCRM em um ambiente Linux Ubuntu, utilizando Docker Compose para garantir isolamento, escalabilidade e facilidade de manutenção.
Pré-requisitos e Preparação do Ambiente
Antes de iniciarmos a instalação, é fundamental definir a infraestrutura adequada. Para rodar o TwentoCRM com desempenho satisfatório, recomenda-se uma VPS com pelo menos 2 vCPUs e 4GB de RAM. Embora seja possível rodar em configurações menores, o banco de dados PostgreSQL e o servidor Node.js consomem recursos significativos durante a indexação e processamento de grandes volumes de contatos.
O sistema operacional base será um Ubuntu Server limpo (versão 22.04 LTS ou superior). A primeira etapa envolve atualizar os pacotes do sistema e instalar as dependências necessárias para gerenciar containers Docker e o Git. Execute os seguintes comandos com privilégios de root ou usuário sudo:
sudo apt update && sudo apt upgrade -y
sudo apt install curl git wget ufw -yEm seguida, precisamos instalar o Docker Engine e o Docker Compose plugin. Utilize o script oficial para garantir a versão mais recente e estável:
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USERApós adicionar seu usuário ao grupo docker, relogue ou reinicie o serviço de containers para aplicar as permissões:
sudo systemctl restart docker
docker --version
docker compose versionVerifique se ambas as versões foram instaladas corretamente. A ausência do docker compose (versão 2) pode causar erros de configuração subsequentes.
Configuração de Segurança Básica com UFW
A segurança é primordial em qualquer instalação self-hosted. O firewall Uncomplicated Firewall (UFW) deve ser configurado para permitir apenas o tráfego essencial: SSH para administração, HTTP e HTTPS para acesso ao CRM, e a porta interna do banco de dados, que não deve ser exposta publicamente.
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enableCom o firewall ativo, seu servidor estará protegido contra acessos indesejados nas portas padrão. No entanto, para fins de teste inicial, você pode permitir temporariamente a porta 8080 (padrão do Twento) se ainda não configurou o Nginx como reverse proxy:
sudo ufw allow 8080/tcpObtenção e Estrutura do Projeto
Agora que o ambiente está pronto, procedemos com a obtenção dos arquivos de configuração. O TwentoCRM utiliza Docker Compose para orquestrar os serviços: banco de dados (PostgreSQL), servidor de aplicação (Node.js) e filas de background tasks (Redis).
sudo mkdir -p /opt/twentycrm
cd /opt/twentycrm
git clone https://github.com/twenty-crm/twenty.git .A estrutura de diretórios resultante conterá o Dockerfile, o docker-compose.yml e scripts de inicialização. É crucial observar que, por padrão, o projeto espera variáveis de ambiente específicas para conectar os serviços. Vamos criar um arquivo de ambiente personalizado para evitar expor senhas em texto puro no código fonte.
cp .env.example .env.localEdite o arquivo .env.local utilizando seu editor de texto favorito (como vim ou nano) e altere as seguintes variáveis críticas:
- APP_URL: Defina como
http://seu-dominio.comou o IP público do servidor. - DB_POSTGRES_DATABASE: Nome do banco de dados (ex: twenty_db).
- DB_POSTGRES_USER: Usuário do banco de dados.
- DB_POSTGRES_PASSWORD: Uma senha forte e complexa gerada por um gerenciador de senhas.
Além disso, defina a chave secreta para as sessões:
NODE_AUTH_SECRET=sua_chave_secreta_aleatoria_muito_longaInicialização dos Serviços com Docker Compose
Com o ambiente configurado, iniciamos a stack. O comando abaixo baixará as imagens necessárias (PostgreSQL, Redis e a imagem base do Node.js) e criará os containers interligados.
docker compose up -d --buildO processo de build pode levar alguns minutos, especialmente na primeira execução, pois o sistema compila as dependências frontend e backend. Monitorize o log para detectar erros:
docker compose logs -fSe a saída indicar sucesso nos containers twenty-db, twenty-redis e twenty-server, a instalação básica foi concluída. Você pode acessar o CRM navegando para http://ip-do-seu-servidor:8080. No entanto, acessar diretamente pela porta 8080 não é recomendado para produção devido à falta de criptografia SSL e gerenciamento inadequado de cabeçalhos HTTP.
Configuração do Reverse Proxy com Nginx
Para tornar o CRM acessível via domínio seguro (HTTPS) e integrar corretamente as funcionalidades de WebSocket e upload de arquivos, configuramos o Nginx como reverse proxy. Primeiro, instale o Nginx:
sudo apt install nginx -yCrie um arquivo de configuração no diretório sites-available:
sudo nano /etc/nginx/sites-available/twenty-crmInsira a seguinte configuração, ajustando o domínio e os caminhos dos certificados:
server {
listen 80;
server_name seu-dominio.com www.seu-dominio.com;
location / {
proxy_pass http://localhost:3000; # Porta interna do app se configurado assim, ou 8080
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;
}
}Atenção: Verifique a porta interna configurada no docker-compose.yml. O TwentoCRM frequentemente expõe a porta 3000 ou 8080. Ajuste o proxy_pass conforme necessário.
Ative o site e teste a configuração:
sudo ln -s /etc/nginx/sites-available/twenty-crm /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginxHabilitação do SSL com Let's Encrypt
A segurança HTTPS é obrigatória para qualquer CRM que lide com dados de clientes. Utilizamos o Certbot para automatizar a obtenção e renovação dos certificados.
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d seu-dominio.com -d www.seu-dominio.comO Certbot irá modificar automaticamente o arquivo de configuração do Nginx para redirecionar todo o tráfego HTTP para HTTPS e inserir os caminhos dos certificados SSL. Reinicie o serviço para aplicar:
sudo systemctl reload nginxPrimeiro Acesso e Configuração Inicial
Acesse https://seu-dominio.com. Você será recebido pela tela de cadastro inicial. Crie a conta de administrador, definindo um nome de empresa e credenciais seguras.
Após o login, explore o dashboard. O TwentoCRM diferencia-se por sua interface baseada em kanban para gestão de pipelines de vendas e uma visão unificada de contatos e empresas. Diferente do Dolibarr instalação Ubuntu, que exige configuração manual de módulos complexos desde o início, o TwentoCRM oferece um fluxo onboarding guiado.
Configure as permissões de equipe. Crie grupos (ex: Vendas, Suporte) e atribua regras de acesso granulares. Isso é crucial para manter a integridade dos dados, especialmente se você estiver migrando de soluções como o espocrm tutorial vps, onde a gestão de permissões pode ser menos intuitiva.
Migração e Integração de Dados
Uma das maiores dores no mercado é a portabilidade de dados. O TwentoCRM suporta importação em massa via CSV. Prepare seus dados exportados do suitecrm self-hosted ou Salesforce, garantindo que os cabeçalhos correspondam aos campos nativos (Nome, Email, Telefone, Empresa).
Para integrações avançadas com ERPs como o erpnext vps tutorial, utilize a API REST do TwentoCRM. A documentação da API é gerada automaticamente pelo Prisma e está disponível via endpoint Swagger/OpenAPI na interface administrativa.
# Exemplo de requisição para listar contatos
curl -X GET "https://seu-dominio.com/api/contacts" \
-H "Authorization: Bearer SEU_TOKEN_ACESSO"Backup e Manutenção Contínua
A responsabilidade pelo backup recai sobre o administrador do sistema. Para o TwentoCRM self-hosted, os pontos críticos são o banco de dados PostgreSQL e o diretório de uploads (anexos e imagens).
Crie um script de backup simples:
#!/bin/bash
BACKUP_DIR="/opt/backups/twenty"
DATE=$(date +%F)
mkdir -p $BACKUP_DIR
# Backup do Banco de Dados
docker exec twenty-db_1 pg_dump -U postgres twenty_db > $BACKUP_DIR/db_$DATE.sql
# Backup dos Arquivos
docker cp twenty-server_1:/app/uploads $BACKUP_DIR/uploads_$DATE.tar.gz
# Compactar e remover backups antigos (ex: manter 7 dias)
tar -czf $BACKUP_DIR/backup_$DATE.tar.gz $BACKUP_DIR/db_$DATE.sql $BACKUP_DIR/uploads_$DATE.tar.gz
find $BACKUP_DIR -name "backup_*.tar.gz" -mtime +7 -deleteAgende este script no crontab para execução diária:
0 2 * * * /opt/scripts/backup-twenty.shVantagens Competitivas do TwentoCRM
Ao escolher o twentycrm self-hosted, você opta por uma arquitetura que escala com seu negócio. A modularidade permite adicionar conectores de e-mail, calendários e ferramentas de projeto sem a necessidade de licenças adicionais por usuário.
Em comparação ao erpnext vps tutorial, que é um ERP completo e pode ser "overkill" se você precisa apenas de CRM, o Twento foca exclusivamente na jornada do cliente, oferecendo uma UX superior. Já em relação ao suitecrm self-hosted, a performance é notavelmente melhor devido à stack JavaScript moderna, eliminando a lentidão comum em consultas SQL pesadas do PHP.
A comunidade open source ao redor do projeto cresce rapidamente, fornecendo plugins e integrações que mantêm a ferramenta atualizada contra as grandes players de mercado. Para sysadmins brasileiros, a possibilidade de hospedar em data centers nacionais (como AWS São Paulo ou Azure Brasil Sul) garante baixa latência e conformidade com a LGPD.
Conclusão
A instalação do TwentoCRM é um processo direto para profissionais familiarizados com Docker e Linux. Ao seguir este guia, você estabelece uma base sólida para gestão de clientes, combinando a flexibilidade do open source com a robustez da infraestrutura cloud moderna. Esta solução representa o equilíbrio ideal entre controle técnico, segurança de dados e experiência do usuário, tornando-se a escolha preferencial para empresas que desejam sair das amarras dos CRMs SaaS caros.
Para dúvidas específicas sobre customizações de banco de dados ou integração com APIs externas, consulte a documentação oficial do projeto no GitHub. A autonomia técnica é o maior ativo na era da soberania digital.