A gestão eficiente de relacionamentos com clientes (CRM) é um pilar fundamental para o crescimento sustentável de qualquer negócio, independentemente do seu porte. No entanto, as soluções proprietárias dominantes frequentemente impõem custos elevados de licenciamento, limitações na personalização e preocupações legítimas sobre a soberania dos dados. É nesse contexto que a abordagem twentycrm self-hosted se destaca como uma alternativa robusta, flexível e transparente para organizações que priorizam o controle total sobre sua infraestrutura.
O Twenty não é apenas mais um software de código aberto; é uma plataforma moderna construída com tecnologias atuais, projetada para ser visualmente intuitiva e tecnicamente poderosa. Ao optar por instalar crm open source como o Twenty, você elimina as taxas mensais recorrentes por usuário e ganha a liberdade total para integrar o sistema aos seus fluxos de trabalho existentes. Este tutorial técnico guiará profissionais de TI, sysadmins e desenvolvedores através do processo completo de implantação desta solução em um ambiente VPS Linux, garantindo uma instalação segura, escalável e pronta para produção.
Pré-requisitos e Preparação do Ambiente
Antes de iniciar a instalação, é crucial preparar o servidor adequadamente. O Twenty exige um ambiente estável com recursos mínimos suficientes para processar requisições simultâneas e armazenar dados relacionais. Recomendamos o uso de uma distribuição Linux baseada em Debian ou Ubuntu, dada a ampla disponibilidade de documentação e suporte da comunidade.
Requisitos de Hardware Mínimos:
- CPU: 2 vCPUs ou superior
- RAM: 4 GB (recomendado 8 GB para cargas maiores)
- Armazenamento: 40 GB SSD ou superior
- Sistema Operacional: Ubuntu 22.04 LTS ou Debian 12
Além dos recursos de hardware, você precisará ter acesso root ou um usuário com privilégios sudo ao seu servidor. Também é essencial que o domínio (ou subdomínio) esteja apontando corretamente para o endereço IP público do seu VPS via registro DNS tipo A.
Etapa 1: Atualização do Sistema e Instalação de Dependências Básicas
A primeira ação consiste em garantir que o sistema operacional esteja atualizado com os últimos pacotes de segurança e correções de bugs. Isso previne conflitos de dependências durante a instalação dos componentes principais.
sudo apt update
sudo apt upgrade -y
Em seguida, instale as ferramentas básicas necessárias para o gerenciamento do sistema, edição de arquivos e comunicação segura:
sudo apt install curl git wget ufw net-tools nano -y
Etapa 2: Configuração do Banco de Dados (PostgreSQL)
O Twenty utiliza PostgreSQL como seu banco de dados principal. Esta escolha garante integridade transacional e performance escalável. Vamos instalar o PostgreSQL e configurar um usuário e banco de dados dedicados para a aplicação.
sudo apt install postgresql postgresql-contrib -y
Após a instalação, acesse o shell do PostgreSQL para criar o banco de dados e o usuário:
sudo -u postgres psql
Dentro do prompt SQL, execute os seguintes comandos. Substitua seusenha por uma senha forte e complexa gerada por um gerenciador de senhas:
CREATE USER twenty WITH PASSWORD 'seusenha';
CREATE DATABASE twentydb OWNER twenty;
\q
Saia do prompt SQL e certifique-se de que o serviço PostgreSQL está ativo e configurado para iniciar automaticamente com o sistema:
sudo systemctl enable postgresql --now
Etapa 3: Instalação do Node.js e Yarn
O backend e o frontend do Twenty são construídos em JavaScript/TypeScript. Para gerenciar as dependências e compilar a aplicação, precisamos instalar o ambiente de execução Node.js (versão LTS recomendada) e o gerenciador de pacotes Yarn.
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
Com o Node.js instalado, proceda com a instalação do Yarn via npm:
npm install --global yarn
Etapa 4: Clonagem e Configuração do Twenty CRM
Agora que o ambiente está preparado, vamos baixar o código-fonte do projeto. Recomendamos criar um diretório específico para a aplicação para manter a organização do sistema de arquivos.
cd /opt
sudo mkdir twenty
sudo chown $USER:$USER /opt/twenty
cd /opt/twenty
git clone https://github.com/twentyhq/twenty.git .
Navegue até o diretório raiz do projeto clonado e copie o arquivo de configuração de exemplo. O .env é onde todas as variáveis de ambiente, incluindo credências do banco de dados e chaves de segurança, serão definidas.
cp .env.example .env
nano .env
Dentro do arquivo .env, você deve editar as seguintes linhas críticas:
- Database URL: Atualize a linha
DB_DATABASE_URLcom as credenciais criadas na Etapa 2. O formato geralmente é:postgresql://twenty:seusenha@localhost:5432/twentydb. - App Secret: Gere uma chave aleatória e segura para esta variável. Ela é usada para assinar sessões e tokens JWT. Você pode gerar uma usando o comando
openssl rand -hex 32. - NODE_ENV: Certifique-se de que a variável está definida como
production.
Salve as alterações no arquivo .env e saia do editor.
Etapa 5: Instalação das Dependências e Build da Aplicação
Com a configuração inicial feita, o próximo passo é instalar todas as dependências do projeto. Este processo pode levar alguns minutos, dependendo da velocidade da sua conexão de rede e da potência do servidor.
yarn install
Após a instalação das dependências, execute a compilação (build) dos ativos estáticos e do backend:
yarn build:server
yarn build:app
Se essas etapas forem concluídas sem erros, seu código fonte está pronto para ser executado. No entanto, para um ambiente de produção, não devemos rodar o aplicativo diretamente pelo terminal. Precisamos de um gerenciador de processos e um servidor web reverso.
Etapa 6: Configuração do Gerenciador de Processos (PM2)
O PM2 é um gerenciador de processos para aplicações Node.js que mantém seus aplicativos vivos, permite o gerenciamento de serviços e oferece balanceamento de carga básico. É a ferramenta padrão da indústria para manter aplicações web rodando em produção.
sudo npm install -g pm2
Inicie a aplicação do backend usando o PM2:
pm2 start server/dist/main.js --name twenty-backend
Para iniciar o servidor da aplicação frontend (que serve os arquivos estáticos compilados), você pode usar um script de inicialização fornecido pelo projeto ou iniciar diretamente a build do app. Verifique se existe um script yarn start:app na configuração do projeto. Caso contrário, utilize:
pm2 start yarn --name twenty-frontend -- start
Salve a lista de processos e configure o PM2 para reiniciar automaticamente em caso de falha ou reinicialização do servidor:
pm2 save
pm2 startup
O último comando retornará um script específico para o seu usuário. Execute esse script no terminal para concluir a configuração de inicialização.
Etapa 7: Configuração do Nginx como Reverse Proxy
O Nginx atuará como uma fachada entre a internet e sua aplicação, lidando com conexões HTTPS, compressão e roteamento de tráfego. Primeiro, instale o Nginx:
sudo apt install nginx -y
Crie um novo arquivo de configuração no diretório sites-available:
sudo nano /etc/nginx/sites-available/twenty-crm
Insira a seguinte configuração, substituindo seu-dominio.com pelo seu domínio real:
server {
listen 80;
server_name seu-dominio.com www.seu-dominio.com;
# Redirecionar todo o tráfego para HTTPS
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name seu-dominio.com www.seu-dominio.com;
# Caminho para os certificados SSL (será configurado no próximo passo)
ssl_certificate /etc/letsencrypt/live/seu-dominio.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/seu-dominio.com/privkey.pem;
# Configurações de Segurança SSL
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
ssl_prefer_server_ciphers on;
# Client Max Body Size: Ajuste conforme necessário para uploads de arquivos
client_max_body_size 50M;
location / {
proxy_pass http://localhost:3000; # Porta padrão do frontend Twenty
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;
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;
}
# Logs
access_log /var/log/nginx/twenty-access.log;
error_log /var/log/nginx/twenty-error.log;
}
Ative a configuração criando um link simbólico para o diretório sites-enabled:
sudo ln -s /etc/nginx/sites-available/twenty-crm /etc/nginx/sites-enabled/
Teste a configuração do Nginx para garantir que não há erros de sintaxe:
sudo nginx -t
Se o teste for bem-sucedido, recarregue o serviço:
sudo systemctl reload nginx
Etapa 8: Configuração de SSL com Let's Encrypt
A segurança HTTPS é obrigatória para qualquer aplicação moderna que lide com dados sensíveis de clientes. Vamos utilizar o Certbot para obter e renovar automaticamente certificados SSL gratuitos.
sudo apt install certbot python3-certbot-nginx -y
Execute o Certbot, selecionando a opção para configurar o domínio do Twenty CRM:
sudo certbot --nginx -d seu-dominio.com -d www.seu-dominio.com
O utilitário irá interagir com você para fornecer um e-mail de contato, aceitar os termos de serviço e decidir se deseja redirecionar todo o tráfego HTTP para HTTPS (recomendado). O Certbot atualizará automaticamente o arquivo de configuração do Nginx com os caminhos corretos dos certificados.
Etapa 9: Segurança e Firewall
Para garantir que apenas as portas necessárias estejam acessíveis, vamos configurar o firewall UFW (Uncomplicated Firewall). Primeiro, verifique se o perfil do Nginx está registrado:
sudo ufw app list
Habilite o acesso SSH (para manter a administração remota), HTTP e HTTPS. Certifique-se de não abrir as portas internas do Node.js ou do PostgreSQL diretamente:
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
Verifique o status do firewall para confirmar que as regras estão ativas:
sudo ufw status verbose
Etapa 10: Backup Automatizado
A instalação técnica é apenas metade da equação. A sobrevivência do seu sistema depende da capacidade de recuperar dados em caso de desastre. Para um twentycrm self-hosted, os backups devem incluir tanto o banco de dados quanto os arquivos anexados armazenados no disco.
Crie um script de backup simples utilizando o utilitário pg_dump para o banco de dados:
sudo nano /opt/twenty/backup.sh
Conteúdo do script:
#!/bin/bash
BACKUP_DIR="/opt/backups"
DATE=$(date +%F)
DB_NAME="twentydb"
DB_USER="twenty"
mkdir -p $BACKUP_DIR
# Backup do Banco de Dados
sudo -u postgres pg_dump $DB_NAME | gzip > $BACKUP_DIR/db_$DATE.sql.gz
# Backup dos Arquivos (se houver uploads locais)
tar -czf $BACKUP_DIR/files_$DATE.tar.gz /opt/twenty/storage/uploads 2>/dev/null
# Remover backups antigos (manter últimos 7 dias)
find $BACKUP_DIR -type f -mtime +7 -delete
Torne o script executável e agende-o via crontab:
sudo chmod +x /opt/twenty/backup.sh
sudo crontab -e
Adicione a seguinte linha para rodar o backup diariamente às 3 da manhã:
0 3 * * * /opt/twenty/backup.sh
Conclusão: Benefícios do CRM Open Source Self-Hosted
Ao concluir estas etapas, você possui uma instância funcional e segura de um CRM para pequenas empresas ou equipes de vendas que exigem controle total. A escolha por uma alternativa salesforce open source como o Twenty não reduz a capacidade da ferramenta; pelo contrário, oferece uma base limpa sobre a qual construir.
Com esta configuração, você economiza custos de licenciamento, garante que os dados dos seus clientes permaneçam em sua infraestrutura e pode personalizar o software conforme a necessidade específica do seu negócio. A combinação de tecnologias modernas com a flexibilidade do software crp (Customer Relationship Planning) auto-hospedado coloca o poder da gestão estratégica nas mãos da sua equipe técnica.
Lembre-se de monitorar os logs do sistema regularmente, atualizar as dependências periodicamente e testar seus backups. A manutenção proativa é o que separa uma instalação temporária de uma infraestrutura crítica de negócios. Agora, sua plataforma está pronta para gerenciar gestão de clientes com eficiência, segurança e escalabilidade.