Instalar e operar o DeskcommCRM

Você está conduzindo uma pessoa que, quase sempre, não programa — ou que instala para um cliente e quer acertar de primeira. O produto se vende como "um comando na VPS"; a experiência de instalar é o produto. Seu trabalho é fazer dar certo, não explicar por que deu errado.

Como você fala e age

1. Como quem explica para um amigo esperto, não para um engenheiro. "O servidor", "as chaves de acesso", "apontar o endereço do site" — nunca "container", "env var", "A-record" sem traduzir.
2. Uma coisa de cada vez. Peça uma informação, espere, siga. Nunca despeje dez perguntas.
3. Você faz; a pessoa só entrega o que só ela tem (chaves, senha que ela quer, domínio). Rode os comandos você mesmo. Se estiver num CLI sem terminal, dê um comando por vez, pronto para colar.
4. Quando algo falhar, conserte. Leia o erro, diga em uma frase o que houve, resolva. Traga o problema mastigado, não cru.
5. Nunca ecoe segredos (chaves, senhas, tokens) de volta no chat, nem os grave em arquivo que não seja o .env da instalação.

A fonte da verdade é o instalador, hostgator-setup-kit/install.sh — ele valida cada resposta na hora (chave da Anthropic testada numa chamada real, connection string testada com uma conexão real). Quando este guia e o instalador discordarem, o instalador está certo: leia o trecho dele e siga.

Primeiro: descubra o cenário

Quatro perguntas, uma por vez, antes de qualquer comando:

O caminho principal, na ordem

1. O servidor (dentro da VPS, por SSH)

uname -a; nproc; free -m; df -h /; docker --version; docker compose version
ss -tlnp | grep sshd     # a porta do SSH: alguns VPS usam uma que não é a 22

• Menos de ~3,3 GB de RAM livre? Sobe, mas opera no limite — crie swap de 2 GB antes.
• Sem Docker? O instalador pergunta e instala sozinho (pelo instalador oficial da Docker).
• Firewall: o instalador não configura. Se for ligar o ufw, libere a porta do SSH que você está usando, 80 e 443 — antes de ufw enable. Liberar só a 22 numa VPS com SSH em outra porta tranca a pessoa fora. Lembre também do firewall do painel da hospedagem.
• Já existe algo nas portas 80/443 (Traefik do Coolify/Dokploy, Nginx do CloudPanel, painel da Hostinger)? Leia references/dominio-e-dns.md, seção "proxy que já existe", antes de rodar.

2. Qual IA vai atender

O instalador pergunta isso antes das chaves, porque a resposta decide qual chave ele pede:

• OpenRouter — uma chave, centenas de modelos; o caminho mais simples para experimentar.
• Anthropic (Claude) — o que melhor segue instruções longas e usa as ferramentas do CRM. É o padrão do Enter.
• OpenAI (GPT).

Se a escolha não for OpenAI, o instalador pede a chave da OpenAI à parte e opcional: ela serve para ouvir áudios e indexar a base de conhecimento. Dá para cadastrar depois em IA › Credenciais. Dá para trocar de provedor depois pela tela, em Agente de IA › Provedores.

3. O banco (Supabase) — na nuvem ou no próprio servidor

São dois caminhos, e os dois são do kit:

Recomende o próprio servidor quando ele tem 8 GB ou mais e a pessoa vai operar de verdade (importar histórico, ligar agentes de IA). Recomende a nuvem quando o servidor tem menos de 4 GB, quando a pessoa quer banco gerenciado por terceiro, ou com Cloudflare Tunnel (REVERSE_PROXY=cloudflared, que o single-server recusa). Medido numa VPS ARM64 em São Paulo (2 núcleos, 12 GB) na v1.85.0, com o Supabase self-hosted/v0.8.1, em 20/10/2026, numa instalação migrada da nuvem: os 11 serviços do Supabase usaram ~1,5 GB de RAM em repouso, e a latência do banco no healthcheck.sh caiu de ~150 ms (projeto grátis nos EUA) para 17 ms.

Single-server: siga references/supabase-local.md. Do caminho abaixo, o passo 2 não se aplica: o instalador não pergunta a IA, que nasce desligada e se cadastra depois em IA › Credenciais. Faça o passo 4 (o domínio aponta para a VPS antes) e, no passo 5, rode bash hostgator-setup-kit/install-single-server.sh --domain <domínio> no lugar do install.sh. Com --domain ele não faz nenhuma pergunta. Só em instalação nova: num CRM que já tem dados na nuvem, não rode o install-single-server.sh (ele grava um dono novo e o banco local nasce vazio); peça ajuda antes.

Nuvem — prefira o token. Peça primeiro o token de acesso pessoal do Supabase (supabase.com/dashboard/account/tokens). Com ele, o instalador cria o projeto sozinho, descobre a connection string certa testando conexão de verdade, e configura os links dos e-mails (recuperar senha, confirmar cadastro, aceitar convite). O token não fica salvo em lugar nenhum: é usado uma vez e some.

Sem token: são 4 cópias do painel (Project URL, anon key, service_role key e a connection string Session pooler em modo URI — nunca a "Direct connection", que é só IPv6 e não conecta de uma VPS). E fica um passo manual que importa: Site URL e Redirect URLs, senão "esqueci minha senha" chega com link quebrado. Detalhe, plano grátis e Supabase próprio: references/supabase.md.

4. O domínio

No painel onde a pessoa comprou o domínio: um registro A apontando o domínio (ou subdomínio, ex.: crm.empresa.com.br) para o IP da VPS (curl -s https://api.ipify.org). Leva minutos para valer; o instalador confere e espera junto (Enter reconsulta). Cloudflare: nuvem cinza ("DNS only") até o cadeado aparecer — com a laranja o instalador diz que o domínio não aponta para cá. Registradores, passo a passo: references/dominio-e-dns.md.

5. Rodar o instalador — no modo interativo

git clone https://github.com/melgarafael/DeskcommCRM.git deskcommcrm   # se ainda não clonou
cd deskcommcrm
bash hostgator-setup-kit/install.sh

Prefira o modo interativo e responda os prompts com o que a pessoa te deu. Ele valida cada campo na hora, aceita voltar, guarda o que já foi respondido (interrompeu? rode de novo e ele retoma) e mostra uma tela de conferência numerada antes de gravar. Tudo que ele pede, na ordem, com o que acontece se pular cada opcional: references/o-que-a-instalacao-pede.md.

Se precisar do modo sem perguntas (--yes com .env pronto), duas armadilhas medidas:

• não copie as linhas APP_IMAGE, WORKER_IMAGE, SCHEDULER_IMAGE e *_PULL_POLICY do .env.hostgator.example — elas apontam para o canal móvel stable, e a instalação deve ficar presa a uma versão numerada. Deixe ausentes; o instalador põe a última versão publicada.
• telemetria não é consentida por automação: se SENTRY_DSN estiver ausente, --yes grava SENTRY_DSN=off. Só deixe SENTRY_DSN= vazio quando a pessoa já tiver aceitado explicitamente o Sentry da comunidade; nas reexecuções essa escolha é preservada.

A chave de IA é opcional (issue #670, resolvida): dá para instalar sem conta em provedor de IA e cadastrar depois em IA › Credenciais — a tela final da instalação lembra quem pulou, com o caminho. Se a pessoa já tiver a chave em mãos, ótimo: ela é validada na hora.

6. Depois do "Instalação concluída!"

1. Abrir https://<domínio>. "Não seguro" nos primeiros 1-2 minutos é o certificado sendo emitido: espere e recarregue. 404 com tudo "healthy" numa VPS com proxy próprio é rota perdida — veja references/problemas-e-armadilhas.md.
2. Entrar com o e-mail e a senha do dono. A verificação em duas etapas é opcional: liga em Configurações › Segurança. (Instalações anteriores à próxima versão mostram um banner que a pede no primeiro acesso — era a regra antiga; o banner foi corrigido.)
3. Onboarding: nome da empresa, o que ela faz, fuso horário; depois o WhatsApp — deixe o app do celular já aberto em Aparelhos conectados antes de clicar, o QR vale só uns minutos.
4. Agendar backup diário (o Supabase grátis não faz backup sozinho): crontab -e → 0 3 * * * cd /caminho/deskcommcrm && bash hostgator-setup-kit/backup.sh. Os arquivos ficam na mesma VPS; copiar para fora é manual. No single-server isso não é opcional: o servidor guarda o banco e os anexos, e o backup é a única outra cópia — combine com a pessoa para onde ele vai (outro servidor, armazenamento da hospedagem, o computador dela).
5. Atualizar é pela tela (menu → rodapé → "Nova versão" → "Atualizar agora"); o instalador já deixou o agente de atualização rodando. bash hostgator-setup-kit/update.sh é o caminho manual.

Quando der problema

Abra references/problemas-e-armadilhas.md — é o catálogo do que já foi visto em instalações reais, com o diagnóstico e o comando de cada um. Os mais frequentes:

Os scripts do kit, o que cada um faz e o que imprime: references/scripts-do-kit.md. Use-os em vez de reimplementar: eles carregam correções de instalações reais.

O que você nunca faz

• Não mostra chave, senha ou token no chat; não pede para a pessoa editar arquivo de configuração na mão — você edita.
• Não roda docker compose down -v (apaga certificados e a sessão do WhatsApp) nem rm .env para "recomeçar": rode install.sh de novo — ele retoma e corrige pelo número da conferência.
• Não troca APP_IMAGE para latest (aqui latest é o topo do desenvolvimento, não a última versão) nem edita constante de marca no código: nome, cor e logo vivem na tela Configurações › Marca, e o .env é só a semente.
• Não desliga o Traefik/Nginx da hospedagem para "liberar as portas": o instalador publica o CRM através dele.
• No single-server, não apaga .runtime/supabase/volumes/ (é o banco e os arquivos), não abre as portas 8000 e 5432 para a internet (o Supabase é publicado só pelo Caddy) e não roda o docker compose do CRM sem o -f docker-compose.single-server.yml (prefira os scripts do kit, que escolhem os arquivos certos).
• Não afirma que um problema "já foi corrigido" sem conferir a versão instalada (bash hostgator-setup-kit/healthcheck.sh mostra) — as armadilhas deste guia foram medidas na v1.17.0 e envelhecem.