Bem-vindo ao Guia de Instalação do Evo CRM Community - Documentação do Evolution Foundation

O Evo CRM Community é a versão gratuita e open-source do Evo CRM. Você instala tudo no seu próprio servidor — os dados ficam com você, sem mensalidades e sem limites de uso.

Prefere não se preocupar com servidor? Contrate um VPS com o Evo CRM já pré-instalado e pronto para usar em minutos. Ver planos HostGator + Evo CRM →

A plataforma é formada por 5 serviços que trabalham juntos:

Serviço	O que faz	Porta
`evo-auth-service-community`	Cuida do login e das permissões de acesso	3001
`evo-ai-crm-community`	Gerencia conversas, contatos e caixas de entrada	3000
`evo-ai-frontend-community`	A interface visual que você usa no navegador	5173
`evo-ai-processor-community`	Executa os agentes de IA	8000
`evo-ai-core-service-community`	Gerencia agentes, pastas e chaves de API	5555

Esta edição não tem painel de administração global, planos de cobrança ou suporte a múltiplas contas. É simples por design.

Antes de Começar

Você vai precisar de três ferramentas instaladas na sua máquina:

Docker e Docker Compose — criam e gerenciam os containers onde cada serviço roda. Clique aqui para instalar
Git — baixa o código do projeto. Clique aqui para instalar
make — simplifica a execução de comandos. Geralmente já vem instalado no Linux e macOS. Clique aqui para instalar

Passo a Passo

Passo 1 — Baixe o projeto

Abra o terminal e execute:

git clone --recurse-submodules [email protected]:evolution-foundation/evo-crm-community.git
cd evo-crm-community

Esse comando baixa o repositório principal e todos os serviços que compõem a plataforma de uma só vez.

Se você já clonou o repositório antes sem a flag --recurse-submodules, rode este comando para baixar os serviços que faltaram:

git submodule update --init --recursive

Passo 2 — Atualize os serviços para a versão mais recente

git submodule update --remote --merge

Isso garante que cada serviço está na versão mais atual. Faça isso sempre que quiser atualizar a plataforma.

Passo 3 — Escolha onde o banco de dados vai rodar

Antes de configurar o .env, decida onde o banco de dados ficará hospedado. Há três opções:

Opção A — Docker (padrão, recomendado para começar)

Não precisa fazer nada. O Docker Compose já sobe um PostgreSQL automaticamente. Pule direto para o Passo 4.

Opção B — PostgreSQL instalado localmente

Prefere instalar o PostgreSQL direto na sua máquina? Use a versão 16 ou superior com a extensão pgVector habilitada.

Sistema	Como instalar
Linux	Guia oficial para Linux
macOS	Postgres.app — a forma mais simples
Windows	Instalador oficial

Depois de instalar, habilite o pgVector no banco:

CREATE EXTENSION IF NOT EXISTS vector;

Opção C — Banco de dados na nuvem

Você também pode usar um serviço gerenciado. Veja as opções compatíveis:

Provedor	pgVector nativo	Documentação oficial
Supabase	✅	supabase.com/docs/…/pgvector
Neon	✅	neon.tech/docs/…/pgvector
AWS RDS	✅	docs.aws.amazon.com/…/PostgreSQL.ExtensionsAndModules
Google Cloud SQL	✅	cloud.google.com/sql/docs/…/extensions
Azure PostgreSQL	✅	learn.microsoft.com/…/how-to-use-pgvector
Railway	✅	docs.railway.app/databases/postgresql

Se você escolheu a Opção B ou C, após criar o banco ajuste estas 5 variáveis no .env (Passo 4):

DB_HOST=localhost       # Endereço do servidor de banco de dados
DB_PORT=5432            # Porta padrão do PostgreSQL
DB_NAME=evo_crm         # Nome do banco que você criou
DB_USER=seu_usuario     # Usuário do banco
DB_PASSWORD=sua_senha   # Senha do banco

O Evo CRM Community não é compatível com MySQL, MariaDB ou SQLite. Use sempre PostgreSQL 16 ou superior com a extensão pgVector habilitada.

Passo 4 — Configure as variáveis de ambiente

cp .env.example .env

Esse comando cria o arquivo .env a partir de um modelo pronto. Abra-o com qualquer editor de texto e ajuste as configurações para o seu ambiente. Se você ficou com a Opção A (Docker), os valores padrão já funcionam. Não precisa alterar nada por enquanto.

Passo 5 — Execute o setup

make setup

Esse único comando cuida de tudo, na ordem certa:

Constrói as imagens Docker de todos os serviços
Sobe o banco de dados e aguarda ele estar pronto
Cria as tabelas e popula os dados iniciais
Inicia todos os serviços

Na primeira execução, o processo pode levar de 15 a 20 minutos. O Docker precisa baixar e compilar todas as imagens. Nas próximas vezes será muito mais rápido.

Passo 6 — Acesse a plataforma

Quando o setup terminar, abra o navegador e acesse:

http://localhost:5173

A plataforma está pronta para uso.

Serviços disponíveis

Interface	Endereço
Frontend	`http://localhost:5173`
CRM API	`http://localhost:3000`
Auth API	`http://localhost:3001`
Processor API	`http://localhost:8000`
Core API	`http://localhost:5555`
Mailhog (e-mail)	`http://localhost:8025`

Comandos do dia a dia

Após o setup, use estes comandos para gerenciar a plataforma:

Comando	O que faz
`make start`	Liga todos os serviços
`make stop`	Desliga todos os serviços
`make restart`	Reinicia todos os serviços
`make status`	Mostra quais containers estão rodando
`make logs`	Exibe os logs de todos os serviços em tempo real
`make logs SERVICE=nome`	Filtra os logs de um serviço específico (ex: `SERVICE=evo-crm`)
`make build`	Reconstrói todas as imagens do zero (sem cache)
`make seed`	Repopula os dados iniciais do banco
`make shell-auth`	Abre um terminal dentro do container do Auth
`make shell-crm`	Abre um terminal dentro do container do CRM
`make shell-core`	Abre um terminal dentro do container do Core
`make shell-processor`	Abre um terminal dentro do container do Processor
`make clean`	Para tudo e apaga todos os dados permanentemente

make clean não tem volta. Ele remove o banco de dados, o cache e todos os arquivos gerados. Use somente se quiser começar do zero.

Próximos passos

Primeiros Passos

Acesse pela primeira vez e configure sua conta

Configurar Canais

Conecte WhatsApp, e-mail, Telegram e outros canais

Configurar Agentes IA

Crie e configure seus agentes de atendimento com IA

Variáveis de Ambiente

Referência completa de todas as variáveis disponíveis

Precisa de ajuda?

GitHub: evolution-foundation/evo-crm-community
Comunidade: evolutionfoundation.com.br/community
Issues: Encontrou um problema? Abra uma issue no repositório do serviço correspondente

​Antes de Começar

​Passo a Passo

​Passo 1 — Baixe o projeto

​Passo 2 — Atualize os serviços para a versão mais recente

​Passo 3 — Escolha onde o banco de dados vai rodar

​Opção A — Docker (padrão, recomendado para começar)

​Opção B — PostgreSQL instalado localmente

​Opção C — Banco de dados na nuvem

​Passo 4 — Configure as variáveis de ambiente

​Passo 5 — Execute o setup

​Passo 6 — Acesse a plataforma

​Serviços disponíveis

​Comandos do dia a dia

​Próximos passos

Primeiros Passos

Configurar Canais

Configurar Agentes IA

Variáveis de Ambiente

​Precisa de ajuda?

Antes de Começar

Passo a Passo

Passo 1 — Baixe o projeto

Passo 2 — Atualize os serviços para a versão mais recente

Passo 3 — Escolha onde o banco de dados vai rodar

Opção A — Docker (padrão, recomendado para começar)

Opção B — PostgreSQL instalado localmente

Opção C — Banco de dados na nuvem

Passo 4 — Configure as variáveis de ambiente

Passo 5 — Execute o setup

Passo 6 — Acesse a plataforma

Serviços disponíveis

Comandos do dia a dia

Próximos passos

Precisa de ajuda?