Instalar com Docker

Esta página é para quem vai instalar o ChatMade no próprio servidor. Ela pressupõe alguém confortável com terminal, Docker e DNS — se você é o dono da operação e não mexe com isso, entregue esta página para quem cuida da sua infraestrutura.

O que sobe

O docker-compose.yml do repositório levanta 7 serviços:

Serviço	O que faz	Porta no host
frontend	O painel (Vue)	3000
backend	A API e o widget (FastAPI)	8000
knowledge_processor	Worker que indexa a base de conhecimento	—
ticket_investigator	Worker que roda a investigação automática de chamados	—
crm_sync	Worker que envia leads para o HubSpot e o Pipedrive	—
db	Postgres 16 com a extensão pgvector	5432
redis	Redis 7	6379

Os três workers rodam a mesma imagem do backend com comandos diferentes. Se você desligar o ticket_investigator, os chamados continuam funcionando — só não investigam sozinhos. Se desligar o knowledge_processor, o conteúdo que você enviar para a base fica na fila e nunca é indexado.

Bom saber: o Postgres precisa da extensão pgvector. Ela é o que guarda os embeddings da base de conhecimento e da deduplicação de chamados. O Dockerfile.postgres do repositório já compila a extensão em cima do postgres:16. Se você for apontar para um Postgres gerenciado que você já tem, confirme que ele oferece pgvector antes.

Antes de começar

• Docker e Docker Compose instalados.
• Cerca de 4 GB de RAM livres. O backend baixa e carrega modelos de embedding no primeiro boot.
• Acesso ao repositório do ChatMade.
• Uma chave de um provedor de IA (OpenAI, Anthropic, Google Gemini, Mistral, xAI, DeepSeek ou Groq). A chave é sua e você cola no painel depois, não no .env.

1. Clone o repositório

git clone <url-do-repositório> chatmade
cd chatmade

2. Crie os arquivos de ambiente

O compose lê backend/.env e frontend/.env. Os dois existem como modelo:

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

3. Gere os três segredos obrigatórios

Fora de ENVIRONMENT=development, a aplicação se recusa a subir enquanto os valores de exemplo estiverem no lugar. Gere cada um:

# JWT_SECRET_KEY e CONVERSATION_SECRET_KEY — 64 caracteres hex, um para cada
openssl rand -hex 32
openssl rand -hex 32

# ENCRYPTION_KEY — chave Fernet com base64 aplicado uma segunda vez
python -c "import base64;from cryptography.fernet import Fernet;print(base64.b64encode(Fernet.generate_key()).decode())"

Cole os três em backend/.env, nas variáveis JWT_SECRET_KEY, CONVERSATION_SECRET_KEY e ENCRYPTION_KEY.

Atenção: a ENCRYPTION_KEY criptografa em repouso as chaves de API dos provedores, as credenciais de OAuth dos canais e do CRM, as mensagens de chat, os resumos de sessão e a memória dos agentes. Perder ou trocar essa chave torna os dados existentes ilegíveis. Guarde um backup dela separado do backup do banco.

4. Ajuste as URLs públicas

Ainda em backend/.env:

• BACKEND_URL — a URL pública deste backend. Não deixe em localhost se for para produção. O widget de chat deriva dela as URLs de API e de WebSocket; se ficar em localhost, o widget embarcado no site do seu cliente não alcança o servidor.
• FRONTEND_URL — a URL pública do painel.
• CORS_ORIGINS — uma lista JSON com as duas URLs acima.
• DATABASE_URL — já vem apontando para o serviço db do compose.
• REDIS_URL — dentro do compose use redis://redis:6379/0.

Em frontend/.env:

• VITE_API_URL — {BACKEND_URL}/api/v1
• VITE_WS_URL — o mesmo host, com ws:// ou wss://
• VITE_WIDGET_URL — igual ao BACKEND_URL

Tudo que estiver abaixo desses blocos no .env.example é opcional: Firebase (só notificação push), S3 (só armazenamento de arquivo fora do disco), e as credenciais de aplicativo do Slack, da Meta, do Jira, do HubSpot, do Pipedrive e do Shopify — que você preenche quando for ligar cada canal ou integração.

Atenção: nas variáveis opcionais, deixe o valor em branco em vez de deixar o texto de exemplo. Um valor não vazio é tratado como credencial de verdade: a requisição sai e falha.

5. Suba

docker compose up -d --build

O primeiro boot demora: o backend baixa os modelos de embedding antes de começar a servir.

6. Rode as migrações

O docker-compose.yml de desenvolvimento substitui o comando de partida do backend por uvicorn --reload, e com isso pula o script que roda as migrações. Rode você mesmo, uma vez:

docker compose exec backend alembic upgrade head

No docker-compose.prod.yml, que usa as imagens prontas e não substitui o comando, o alembic upgrade head roda sozinho a cada partida do container. Nesse caso, pule este passo.

7. Crie a organização e o administrador

Abra http://localhost:3000 (ou o seu FRONTEND_URL). Como ainda não existe nenhuma organização, o painel te leva direto para a tela de setup, com o título Welcome to ChatterMate. Os campos são Organization Name (“Nome da organização”), Domain (“Domínio”), Timezone (“Fuso horário”), Business Hours (“Horário comercial”) e os dados do primeiro administrador: Admin Name, Admin Email e Admin Password.

A senha do administrador precisa ter no mínimo 8 caracteres, com maiúscula, minúscula, número e caractere especial — a tela verifica os cinco antes de deixar você enviar.

Bom saber: o painel se identifica como ChatterMate em toda a interface — na tela de setup, no login, no rodapé e nas mensagens de erro. É o nome do projeto de código sobre o qual o ChatMade é construído. Não há tradução da interface: tudo em inglês.

Atenção: o cadastro é de instância única. Depois que a primeira organização existe, uma segunda tentativa de criar organização recebe 403. Uma instalação atende uma empresa. Não há autocadastro público neste sistema — a única porta de entrada é essa tela de setup — e não há convite por e-mail nem redefinição de senha por e-mail. O administrador cria cada usuário já com a senha definida.

8. Configure o provedor de IA

Com o administrador logado, abra Settings → AI Configuration (“Configurações → Configuração de IA”) e cole a chave do seu provedor. A chave é testada ao vivo antes de ser salva e fica criptografada no banco. Sem essa etapa, o agente não responde.

Produção

Para produção existe o docker-compose.prod.yml, que usa as imagens publicadas em vez de construir localmente, expõe o frontend na porta 80 e roda o backend com Gunicorn atrás de um worker Uvicorn. Você continua responsável pelo proxy reverso e pelo certificado TLS.

Há também um conjunto pronto para Coolify em deploy/coolify/, com um compose específico, um modelo de variáveis de ambiente e um script de deploy pela API do Coolify. Nesse arranjo o painel e a API ficam em hosts separados: o nginx do frontend remove o prefixo /api/ no proxy, o que não combina com o API_V1_STR=/api/v1 do backend, então o painel fala direto com o backend em um domínio próprio.

Bom saber: não existe CLI de instalação neste sistema. Nada de chattermate-deploy ou chattermate-cli — os caminhos reais são os que estão nesta página: clonar, configurar o .env, docker compose up e as migrações do Alembic.

Próximo passo

Com a instância no ar, siga para Canais de atendimento e ligue o primeiro canal — ou vá direto para Atendentes e grupos para criar o resto do time.