DeskcommCRM: instalando o CRM na sua VPS

Olá meus Unicórnios! 🦄✨

Sabe aquela sensação de olhar para uma ferramenta paga e pensar "isso aí é um banco de dados com uma tela bonita, eu consigo rodar sozinha"? 😅 Pois é. Foi mais ou menos assim que eu cheguei no DeskcommCRM: um CRM de código aberto, feito para atendimento por WhatsApp, que roda no seu servidor.

O que me fisgou não foi a lista de recursos. Foi a promessa do instalador: um comando só. E eu sou desconfiada com promessa de um comando só, porque quase sempre significa "um comando só, depois de você já ter feito outras sete coisas". 🙄

Então fui instalar de verdade, numa VPS limpa, para contar aqui o que o comando faz, o que ele pede antes e onde ele para. Este artigo é o caminho inteiro: da VPS recém-criada até o painel aberto no navegador, com o funil de vendas já montado.

🎁 O que vem dentro

Antes de sujar as mãos, o que essa instalação te entrega:

E os quatro motivos que fazem alguém preferir isso a contratar um SaaS pronto:

🧾 O que você precisa ter em mãos antes de começar

Aqui está a lista honesta, e ela é curta. Se faltar um destes três, o instalador para no meio e você vai ter de sair correndo atrás:

• Uma VPS com Ubuntu. O projeto recomenda 4 GB de RAM. Não é exagero: são sete contêineres rodando ao mesmo tempo.
• Um domínio apontando para ela. Um registro do tipo A, com o IP da VPS. Já já eu mostro um truque para quem ainda não comprou domínio nenhum.
• Um banco Supabase. O CRM guarda tudo lá: contatos, conversas, funis. A conta gratuita serve para começar.

Repare no que não está na lista: Node.js, pnpm, compilador, nada disso. A imagem do app já vem pronta, e é um alívio genuíno: compilar aplicação Next.js numa VPS pequena é aquele tipo de espera que faz a gente questionar as escolhas da vida. 😂

🔑 Entrando na VPS

Conecte no servidor com o IP que a hospedagem mandou:

ssh root@SEU_IP_AQUI

Daqui em diante tudo acontece dentro dessa sessão.

🐳 Instalando o Docker

O CRM inteiro roda em contêiner, então o Docker é a base de tudo. Se a sua VPS já veio com ele, pule este pedaço; se não, o script oficial resolve numa linha:

curl -fsSL https://get.docker.com -o instalar-docker.sh
sh instalar-docker.sh

O que cada pedaço faz: o curl baixa o script do site oficial do Docker e o -o salva num arquivo com esse nome; o sh executa o arquivo baixado. Leva uns minutos e imprime bastante coisa.

Para conferir que deu certo, peça a versão dos dois programas que vamos usar:

docker --version
docker compose version

A resposta na minha VPS:

Docker version 29.8.1, build 4a63305
Docker Compose version v5.5.1

🌐 O domínio: o ponto onde quase todo mundo trava

Este é o requisito que mais pega gente desprevenida, e vale entender por que ele existe em vez de só obedecer.

O instalador configura HTTPS automático com Let's Encrypt, aquele cadeadinho verde do navegador. E o Let's Encrypt tem uma regra que não se negocia: ele emite certificado para nome, nunca para IP puro. Não adianta pedir bonito.

O caminho é o de sempre: no painel de quem registrou o seu domínio, crie um registro A com o nome que você quiser (por exemplo crm) apontando para o IP da VPS. Fica crm.suaempresa.com.br. Costuma valer em poucos minutos.

Para conferir que o nome está resolvendo antes de seguir, pergunte ao próprio Ubuntu:

getent ahosts crm.suaempresa.com.br

Se aparecer o IP da sua VPS na resposta, está pronto. O instalador vai conferir isso sozinho também, e se o DNS ainda não tiver propagado ele espera junto com você, oferecendo reconsultar quantas vezes quiser. Detalhe de carinho que eu achei ótimo: ele não mata a instalação por causa disso.

Se o seu domínio está na Cloudflare, leia isto antes

Se você usa Cloudflare e deixou o registro com a nuvenzinha laranja ligada (o tal "proxy ativo"), tem uma armadilha esperando você, e ela é daquelas que fazem a gente duvidar da própria sanidade: o painel do CRM abre, redireciona, abre, redireciona, e o navegador desiste com um erro de redirecionamento demais.

O motivo é uma briga silenciosa entre as duas pontas. Na Cloudflare, o modo de criptografia Flexible significa: "eu falo HTTPS com o visitante, mas falo HTTP com o seu servidor". Só que o Caddy que o instalador sobe faz o contrário: ele recebe uma conexão HTTP e responde "vá para o HTTPS". A Cloudflare obedece, tenta de novo... em HTTP. E assim os dois ficam se empurrando para sempre. 🔁

Há dois jeitos de resolver, e a escolha depende de uma coisa só: se você pode mexer no modo de criptografia da sua conta.

Se o domínio do CRM é o único ali, troque o modo em SSL/TLS › Overview para Full (strict). A Cloudflare passa a falar HTTPS com a VPS, o Caddy para de redirecionar, e o cadeado fica válido de ponta a ponta.

Se você não pode mexer no modo, a saída é dizer ao Caddy que ele não precisa cuidar do HTTPS, porque a Cloudflare já cuida. Abra o Caddyfile com o nano, ache a primeira linha do bloco do site e acrescente http:// na frente:

http://{$DOMAIN} {
	encode gzip

Salve com Ctrl+O, Enter, Ctrl+X, e reinicie só o Caddy:

docker compose -f docker-compose.prod.yml restart caddy

Pronto: o Caddy passa a servir HTTP puro e o loop acaba na hora. O tráfego entre a Cloudflare e a sua VPS anda sem criptografia nesse arranjo, o que é aceitável para muita gente e inaceitável para outra tanta. Se você quiser o melhor dos dois, a Cloudflare permite criar uma Configuration Rule que aplica Full (strict) só naquele hostname, sem tocar no resto da zona.

🗄️ O banco: criando o projeto no Supabase

O CRM não traz banco de dados embutido. Ele fala com um Supabase, que é um Postgres com autenticação e armazenamento de arquivos por cima.

São quatro informações para copiar de lá, e elas moram em dois lugares diferentes do painel. Vamos com calma, porque errar uma delas é o motivo número um de instalação que trava no meio.

Criando a conta e o projeto

Entre em supabase.com e crie sua conta (dá para entrar com o GitHub, que poupa mais uma senha na sua vida). Na primeira vez, o Supabase pede para criar uma organização antes do projeto: é só um nome, e serve para agrupar projetos.

Com a organização criada, clique em New project. O formulário pede quatro coisas:

• Name: o nome do projeto, só para você se achar depois.
• Database Password: a senha do Postgres. Copie e guarde num lugar seguro agora, porque ela não aparece de novo. Use o botão Generate a password se quiser uma boa.
• Region: escolha a mais perto de quem vai usar. Se sua operação é no Brasil, South America (São Paulo) corta um bom tanto de latência.
• Pricing plan: o gratuito serve para começar.

Repare no aviso amarelo que aparece assim que você digita a senha: "If using the Postgres connection string, you will need to percent-encode the password". Guarde essa frase, porque ela volta a importar daqui a pouco. O Supabase avisa antes; eu só entendi o tamanho do aviso depois. 😅

Clique em Create new project e vá tomar um café: a criação leva uns dois minutos, e o painel fica montando o banco enquanto isso. 💤

Projeto no ar, status Healthy. A faixa Get connected ali embaixo é um atalho bem-vindo: o Direct leva à connection string e o API Keys às chaves, que é justamente o que a gente precisa agora.

Onde ficam as chaves

Projeto pronto, abra Project Settings (o ícone de engrenagem, no canto inferior esquerdo) e depois API Keys. E aqui você vai encontrar uma tela com duas abas, que é a parte que me fez parar e reler:

A primeira aba, Publishable and secret API keys, é o sistema novo do Supabase. A segunda, Legacy anon, service_role API keys, é o sistema antigo. E o instalador do DeskcommCRM pede as do sistema antigo.

Na aba legada estão dois dos quatro valores:

• anon / public: a chave pública, que o navegador enxerga. Vem à mostra, com um botão Copy.
• service_role / secret: a chave administrativa, escondida atrás de um Reveal. Repare que o próprio Supabase escreve ao lado dela: "Never share it publicly".

O terceiro valor, a Project URL, aparece logo abaixo do nome do projeto na tela inicial, no formato https://SEU-PROJETO.supabase.co. Ela também está em Integrations › Data API, com o /rest/v1/ no fim: para o instalador, use a URL sem esse sufixo.

O quarto valor está em outro lugar: Project Settings › Database, na seção Connection string, aba URI.

E aqui mora uma armadilha que custa tempo de gente experiente: o Supabase oferece duas connection strings, a Direct connection e a do Session pooler. Pegue a do Session pooler.

O motivo é cruel de tão específico: a Direct connection só existe em IPv6, e a maioria das VPS é IPv4. Ou seja, ela nunca vai conectar, e o erro que aparece não diz nada sobre IPv6. O instalador conhece essa pegadinha e recusa a string errada explicando o que fazer, o que me poupou de descobrir na marra.

⚡ O comando único, finalmente

Com Docker instalado, domínio apontando e as chaves do Supabase na mão, é hora. Dentro da VPS:

git clone https://github.com/melgarafael/DeskcommCRM.git
cd DeskcommCRM
bash hostgator-setup-kit/install.sh

Linha por linha: o git clone baixa o projeto inteiro para uma pasta nova; o cd entra nela; o bash executa o instalador. É isso mesmo, são três linhas e a promessa se cumpre.

O instalador trabalha em quatro fases, e ele anuncia cada uma: prepara o servidor, colhe as suas informações, cuida do banco e do domínio, e por fim coloca o CRM no ar.

Ele pergunta só o que é seu (domínio, as quatro chaves do Supabase, o e-mail e a senha do primeiro admin) e valida cada resposta na hora. Chave errada ele recusa ali mesmo, não três passos adiante quando você já esqueceu o que digitou. Isso parece detalhe e não é: errar uma chave e só descobrir no fim é o que transforma uma instalação de dez minutos numa tarde perdida.

Do resto ele cuida sozinho:

• Gera todos os segredos técnicos. Você não inventa senha nenhuma além da do admin.
• Cria as extensões do Postgres e aplica o schema completo.
• Cria o primeiro admin com o e-mail e a senha que você escolheu.
• Sobe a stack inteira com HTTPS automático e confere a saúde no fim.
• Instala o cron das automações e o agente que faz existir o botão "Atualizar agora" na tela.

Quando termina, a tela diz o que fazer em seguida:

Instalação concluída!

  1. Acesse:  https://SEU_DOMINIO_AQUI
     (o SSL leva ~1min pra emitir no primeiro acesso)

  2. Faça login com:
       e-mail: SEU_EMAIL_AQUI
       senha:  (a que você definiu)

  3. Conecte o WhatsApp (2º passo do onboarding)

🩺 Conferindo que subiu mesmo

Antes de abrir o navegador, dá para perguntar ao próprio servidor se está tudo de pé. O kit traz um verificador:

bash hostgator-setup-kit/healthcheck.sh

Ele lista os contêineres e consulta a saúde interna do app. A saída na minha instalação, resumida nas duas partes que importam:

app         Up 35 minutes (healthy)
caddy       Up 38 minutes
redis       Up 35 minutes (healthy)
scheduler   Up 35 minutes (healthy)
srh         Up 35 minutes
waha        Up 35 minutes
worker      Up 35 minutes (healthy)

São os sete contêineres que eu mencionei lá no começo. E a saúde interna, que é a parte realmente informativa, porque ela pergunta a cada dependência se está respondendo:

{
    "data": {
        "status": "healthy",
        "version": "1.35.0",
        "checks": {
            "supabase": { "status": "ok", "latency_ms": 10 },
            "redis":    { "status": "ok", "latency_ms": 5 },
            "waha":     { "status": "ok", "latency_ms": 6 }
        }
    }
}

Três dependências, três ok, e a latência de cada uma em milissegundos. Se o Supabase estivesse com a chave errada, é aqui que apareceria, não numa tela branca misteriosa no navegador.

🔓 O primeiro acesso

Agora sim, o navegador. Abra https://SEU_DOMINIO_AQUI e você cai na tela de entrar:

Use o e-mail e a senha do admin que você definiu durante a instalação. Repare que a tela já mostra o nome do sistema logo abaixo do "Entrar": se você tiver escolhido um nome próprio na instalação, é ele que aparece ali.

🧭 O onboarding, passo a passo

Entrando pela primeira vez, o CRM não joga você num painel vazio perguntando "e agora?". Ele abre um roteiro de seis passos, e eu gostei bastante do tom dele: em vez de falar de "entidades" e "pipelines", ele fala de um funcionário que vai atender seus clientes.

Repare no quadrinho do meio, que é a parte mais útil da tela. Ele mostra o que já está de pé e o que falta, com bolinha verde e amarela:

• 🟢 Servidor no ar e banco de dados instalado
• 🟡 Falta a chave da inteligência artificial
• 🟢 WhatsApp pronto para conectar seu número
• 🟢 Funil de vendas criado: Pedidos

Ou seja: a instalação entregou tudo, menos a chave de IA, que é opcional e a gente cadastra mais adiante neste mesmo artigo. O funil padrão já veio pronto, o que evita aquele começo de "crie seu primeiro funil" quando você ainda nem sabe o que é um funil ali dentro.

O primeiro passo pede o nome do negócio, uma linha sobre o que vocês fazem e a região de atendimento. A linha do "o que vocês fazem" não é enfeite: é com ela que o agente aprende com quem está falando. Preenchi com uma loja fictícia e segui.

📱 O passo do WhatsApp

O segundo passo é onde o CRM ganha um telefone. E ele começa perguntando algo que raramente se pergunta:

São três jeitos diferentes de ter WhatsApp para empresa, e cada um conecta de um jeito:

• Leio um código com o celular. É o caso de quase todo mundo: você aponta a câmera do WhatsApp para um QR code na tela.
• Tenho conta oficial na Meta. Você cadastrou o número na Meta e tem as credenciais. Não usa celular.
• Contrato de um provedor parceiro. Uma empresa cuida do seu WhatsApp e te deu uma chave.

E tem uma frase logo acima das opções que vale ouro e passa despercebida: "Novos canais começam em modo de teste". Traduzindo: o número recém-conectado não sai respondendo cliente sozinho. Você precisa autorizar depois, explicitamente. É exatamente a proteção que a gente quer quando está montando a coisa e ainda não confia nela.

Escolhendo a opção do QR code, a tela do pareamento é esta:

O caminho no celular vem escrito ali em cima: WhatsApp → Aparelhos conectados → Conectar um aparelho, e aponte para o código.

Dois conselhos práticos: deixe o celular já aberto nessa tela antes de clicar em conectar, porque o QR vale só alguns minutos; e se expirar, não precisa recomeçar nada: o próprio CRM tem o botão de gerar um novo.

Todos os passos do onboarding têm um "Pular por enquanto", e isso é mais generoso do que parece: dá para chegar no painel e voltar depois em cada item, sem ficar preso num roteiro de seis telas quando você só queria dar uma olhada.

✅ Chegando ao fim do roteiro

Terminado o roteiro, ele mostra o balanço do que ficou pronto e do que você deixou para depois:

Repare que ele marca item por item o que foi pulado, sem drama e sem tentar te empurrar de volta. E logo abaixo vem uma seção chamada "O que mais tem aqui", com cartões curtos explicando cada área do sistema: as conversas, o quadro de clientes, os follow-ups, o radar de quem esfriou.

A frase que abre a seção é a melhor da tela inteira: "Você não precisa mexer em nada disso agora. É só para saber que existe." 🥹

🏠 O painel, enfim

Clicando em "Começar a usar", você cai na caixa de entrada, que é o coração do sistema:

O menu da esquerda organiza tudo em cinco blocos, e dá para entender o sistema inteiro só lendo ele:

• Atendimento: Inbox, Radar, Agenda, Respostas rápidas
• CRM: Funis, Contatos, Tarefas
• Agente de IA: Agentes, Follow-ups, Roteadores
• Canais: Conexões, Webhooks
• Análise: Desempenho, Meta Ads, Atividades

A caixa está vazia, claro, e ela avisa isso com todas as letras: "Quando chegarem mensagens, elas aparecem aqui em tempo real." No topo, o nome do negócio que eu digitei no primeiro passo já está lá, num seletor, e é por ali que se troca de empresa quando existe mais de uma.

Em Funis, aquele funil "Pedidos" que o instalador criou sozinho está esperando:

Ele vem marcado como Padrão, o que significa que todo contato novo cai nele enquanto você não disser o contrário. Dá para renomear, arquivar, criar outros, e tem até importação por planilha, que é como a maioria das pessoas realmente traz a carteira de clientes antiga.

E em Conexões fica o painel dos canais, onde se administra cada número depois de conectado:

As quatro abas do topo são os quatro caminhos de canal, e aquele aviso do modo de teste reaparece aqui: "Novos canais começam em modo de teste, sem respostas automáticas até você autorizar números ou liberar o público." A mesma proteção, dita de novo no lugar em que ela importa.

🤖 Ligando a inteligência artificial

Você deve ter reparado na bolinha amarela lá do começo: "Falta a chave da inteligência artificial". Isso é o esperado, e o instalador termina dizendo exatamente isso.

O CRM sobe inteiro e funcional sem nenhuma chave. O que não funciona é o agente responder sozinho: ele fica esperando uma credencial existir. Então vamos ligar isso agora, que é a parte que transforma o CRM instalado em CRM que atende.

E tem um detalhe de arquitetura que eu achei muito elegante: a chave fica cifrada no banco (AES-256-GCM), não no arquivo .env. Consequência prática para quem opera: cadastrar ou trocar a chave não exige reiniciar contêiner nenhum. Quem já derrubou uma aplicação em produção só para trocar uma variável de ambiente sabe o tamanho desse presente. 🎁

Passo 1: cadastrar a chave

No menu lateral, vá em Agente de IA › Ver tudo em IA e depois em Chaves de acesso à IA. A tela começa vazia, com um convite honesto: "Nenhuma chave cadastrada ainda".

Clique em Adicionar credencial e o formulário abre:

São três campos, e o primeiro é o que mais engana:

• Provedor: ele abre em Anthropic (Claude). Se a sua chave é da OpenAI, troque aqui antes de colar, senão a validação recusa uma chave perfeitamente boa. As opções são Anthropic, OpenAI, Google (Gemini) e OpenRouter.
• Nome: um apelido só para você (Producao, por exemplo). Serve para quando houver mais de uma.
• API key: cole a chave inteira. Ela some da tela assim que você salva, e nunca mais volta, nem para você.

Clique em Salvar e validar. O botão não é enfeite: ele conversa com o provedor ali na hora. Se a chave estiver certa, aparece o aviso verde dizendo quantos modelos ela alcança.

Repare no cartão: o CRM guarda o nome, a contagem de modelos e os quatro últimos caracteres da chave. O resto está cifrado no banco. É assim que ele consegue mostrar qual chave é sem nunca poder ler a chave de volta.

Passo 2: dizer quem manda

Aqui mora a armadilha que me custou tempo: cadastrar a chave não troca o provedor. São duas decisões separadas, em duas telas diferentes. Você pode ter uma chave da OpenAI cadastrada e validada enquanto o sistema inteiro continua tentando falar com a OpenRouter.

Vá em Agente de IA › Provedores:

A frase do topo explica tudo: "Seu sistema usa inteligência artificial em 25 lugares diferentes". São 25 pontos, e o Modelo padrão vale para os 24 que você não configurou um a um. Escolha o provedor e o modelo, clique em Salvar padrão, e repare nos blocos abaixo mudando junto: "Atender o cliente" e "Entender a conversa" passam a mostrar gpt-4o.

Passo 3: criar o agente

Em Agente de IA › Agentes, a tela também começa vazia. Clique em Novo agente e preencha o essencial: um Nome (o meu virou "Atendente da Loja"), a empresa de inteligência artificial, o modelo e a chave de acesso que você acabou de cadastrar. O campo das instruções já vem com um texto de partida: "Você é um atendente. Responda de forma educada e clara, em pt-BR."

Clique em Criar agente. Ele nasce como rascunho v1, e isso é proposital: nada dele chega a cliente nenhum enquanto você não publicar.

Passo 4: o teste, antes de qualquer cliente

Esta é a melhor parte, e é onde o CRM ganhou o meu respeito. A aba Teste da tela do agente deixa você conversar com ele sem enviar nada pelo WhatsApp. O aviso é explícito: "Modo teste consome créditos do provider. Nenhuma mensagem é enviada via WhatsApp. O run é registrado como dry-run."

Escrevi a pergunta mais banal que um cliente faria, e mandei executar:

Status ok, e a resposta veio assim:

Olá, Teste! Sim, fazemos entregas para Curitiba. O prazo de entrega depende do produto e da disponibilidade, mas geralmente leva de 3 a 5 dias úteis. Posso ajudar com mais alguma coisa?

Funcionou. Mas o que me fez parar e reler foi o rodapé daquele resultado, não a resposta. O CRM analisou o que o próprio agente escreveu e levantou a mão:

frase suspeita: "O prazo padrão para entrega é de 3 a 5 dias úteis" — isso é uma promessa/compromisso fora do playbook que a validação de valores estruturados não pega; reformule sem prometer prazo, cortesia, gratuidade, brinde ou garantia não autorizada antes de reenviar.

Leia de novo com calma, porque é sutil: o modelo inventou um prazo de entrega. Ninguém disse a ele que a loja entrega em 3 a 5 dias úteis. Ele deduziu, escreveu com toda a confiança do mundo, e isso teria virado uma promessa da sua empresa para um cliente real. A camada de proteção pegou. 😮

Foi ali que a frase do menu, "Proteger a operação: barrar manipulação e promessa que a empresa não pode cumprir", deixou de ser texto de vitrine e virou uma coisa que eu vi acontecer.

O painel ainda lista, logo abaixo, as ações propostas que precisam de autorização separada (no meu teste, update_lead_state). Ou seja: mesmo que o agente decida mexer no funil, isso passa por uma segunda porta.

Só depois de olhar esse relatório é que vale clicar em Publicar v1. E, sinceramente, eu passaria umas boas dezenas de mensagens de teste ali antes de soltar o bicho no WhatsApp de cliente. 😅

🔧 Os comandos que você vai querer guardar

O instalador termina imprimindo uma listinha de comandos, e ela é boa demais para ficar perdida no meio da saída. Todos rodam de dentro da pasta DeskcommCRM:

docker compose -f docker-compose.prod.yml logs -f app
docker compose -f docker-compose.prod.yml restart
bash hostgator-setup-kit/update.sh
bash hostgator-setup-kit/backup.sh

O que cada um faz, na ordem: mostra os logs do app ao vivo (o -f é de follow, e sai com Ctrl+C); reinicia os contêineres; atualiza o CRM para a versão nova; faz backup.

E um que salva o dia quando alguém esquece a senha:

bash hostgator-setup-kit/reset-password.sh SEU_EMAIL_AQUI

🎯 Onde isso chegou

Três linhas de comando, quatro chaves copiadas do Supabase, um registro A no DNS. Do outro lado: sete contêineres no ar, HTTPS válido, banco com o schema aplicado, primeiro admin criado, funil de vendas montado e um painel que explica a si mesmo.

A promessa do "um comando só" se cumpre, com a ressalva honesta de que ela mora na fase 4 de 4: as três primeiras são você juntando domínio, banco e Docker. Mas essas você faria de qualquer jeito, com qualquer sistema.

O que realmente me conquistou não foi a velocidade, foi o cuidado: validar cada resposta na hora em vez de três passos depois, recusar a connection string de IPv6 explicando o porquê, avisar que canal novo nasce em modo de teste, e dizer "você não precisa mexer em nada disso agora". São escolhas de quem já viu gente se perder nesses lugares. 💜

Por hoje é só, meus unicórnios! 🦄✨

Que a magia do arco-íris continue brilhando em suas vidas! Até mais! 🌈🌟