> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolutionfoundation.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Bem-vindo ao Guia de Instalação do Evo CRM Community
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 →](/infraestrutura/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](https://docs.docker.com/get-docker/)
* **Git** — baixa o código do projeto. [Clique aqui para instalar](https://git-scm.com/)
* **make** — simplifica a execução de comandos. Geralmente já vem instalado no Linux e macOS. [Clique aqui para instalar](https://www.gnu.org/software/make/)
***
## Passo a Passo
### Passo 1 — Baixe o projeto
Abra o terminal e execute:
```bash theme={null}
git clone --recurse-submodules git@github.com: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:
```bash theme={null}
git submodule update --init --recursive
```
### Passo 2 — Atualize os serviços para a versão mais recente
```bash theme={null}
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](https://www.postgresql.org/download/linux/) |
| **macOS** | [Postgres.app](https://postgresapp.com/) — a forma mais simples |
| **Windows** | [Instalador oficial](https://www.postgresql.org/download/windows/) |
Depois de instalar, habilite o pgVector no banco:
```sql theme={null}
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](https://supabase.com/docs/guides/database/extensions/pgvector) |
| **Neon** | ✅ | [neon.tech/docs/…/pgvector](https://neon.tech/docs/extensions/pgvector) |
| **AWS RDS** | ✅ | [docs.aws.amazon.com/…/PostgreSQL.ExtensionsAndModules](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/PostgreSQL.ExtensionsAndModules.html) |
| **Google Cloud SQL** | ✅ | [cloud.google.com/sql/docs/…/extensions](https://cloud.google.com/sql/docs/postgres/extensions) |
| **Azure PostgreSQL** | ✅ | [learn.microsoft.com/…/how-to-use-pgvector](https://learn.microsoft.com/azure/postgresql/flexible-server/how-to-use-pgvector) |
| **Railway** | ✅ | [docs.railway.app/databases/postgresql](https://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):
```env theme={null}
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
```bash theme={null}
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
```bash theme={null}
make setup
```
Esse único comando cuida de tudo, na ordem certa:
1. Constrói as imagens Docker de todos os serviços
2. Sobe o banco de dados e aguarda ele estar pronto
3. Cria as tabelas e popula os dados iniciais
4. 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
Acesse pela primeira vez e configure sua conta
Conecte WhatsApp, e-mail, Telegram e outros canais
Crie e configure seus agentes de atendimento com IA
Referência completa de todas as variáveis disponíveis
***
## Precisa de ajuda?
* **GitHub**: [evolution-foundation/evo-crm-community](https://github.com/evolution-foundation/evo-crm-community)
* **Comunidade**: [evolutionfoundation.com.br/community](https://evolutionfoundation.com.br/community)
* **Issues**: Encontrou um problema? Abra uma issue no repositório do serviço correspondente
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.