> ## 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.

# Variáveis de Ambiente

O arquivo `.env` é onde você diz para a plataforma como ela deve se comportar: onde está o banco de dados, qual senha usar, quais serviços se comunicam entre si. Sem ele configurado corretamente, nada funciona.

A boa notícia: para a maioria das instalações com Docker, você **não precisa mudar quase nada**.

***

## Como funciona

Toda a configuração fica em **um único arquivo `.env`** na raiz do projeto. Ele é criado a partir de um modelo pronto:

```bash theme={null}
cp .env.example .env
```

O `.env.example` já vem com valores padrão que funcionam imediatamente para rodar a plataforma localmente com Docker. Abra o `.env` com qualquer editor de texto e ajuste apenas o que for necessário para o seu ambiente.

<Note>
  O arquivo `.env.example` é o arquivo com a lista completa de todas as variáveis disponíveis.
  Consulte-o sempre que precisar de uma referência completa.
</Note>

***

## Banco de dados (PostgreSQL)

Todos os serviços compartilham o mesmo banco de dados. Com Docker, essas variáveis já estão configuradas e funcionam sem alteração.

```bash theme={null}
# Servidor e porta
POSTGRES_HOST=postgres
POSTGRES_PORT=5432

# Credenciais
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=sua_senha_segura

# Nome do banco
POSTGRES_DATABASE=evo_community
```

O serviço **Core** (`evo-ai-core-service-community`) usa um conjunto separado de variáveis com o mesmo banco:

```bash theme={null}
DB_HOST=postgres
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=sua_senha_segura
DB_NAME=evo_community
DB_SSLMODE=disable
```

O serviço **Processor** usa o formato de string de conexão:

```bash theme={null}
POSTGRES_CONNECTION_STRING=postgresql://postgres:sua_senha_segura@postgres:5432/evo_community
```

<Warning>
  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.
</Warning>

***

## Redis (cache e filas)

O Redis é usado para manter sessões ativas e processar tarefas em segundo plano. Com Docker, ele já sobe automaticamente.

```bash theme={null}
# Auth e CRM usam URL completa
REDIS_URL=redis://:sua_senha_redis@redis:6379
REDIS_PASSWORD=sua_senha_redis

# Processor usa variáveis separadas
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_DB=0
REDIS_SSL=false
```

***

## Secrets compartilhados

Essas são as variáveis mais importantes para a segurança da plataforma. Elas devem ter o **mesmo valor** em todos os serviços que as utilizam.

```bash theme={null}
# Usado por: auth, crm, core-service (assinatura de tokens JWT)
SECRET_KEY_BASE=gere-uma-chave-longa-e-aleatoria-com-rails-secret
JWT_SECRET_KEY=gere-uma-chave-longa-e-aleatoria-com-rails-secret

# Usado por: core-service, processor (criptografia de chaves de API)
ENCRYPTION_KEY=gere-uma-chave-base64-de-32-bytes

# Usado por: auth, crm, processor (autenticação entre serviços)
EVOAI_CRM_API_TOKEN=gere-um-uuid-unico-aqui
```

**Como gerar os valores:**

```bash theme={null}
# Para SECRET_KEY_BASE e JWT_SECRET_KEY
make shell-auth
# dentro do container:
rails secret

# Para ENCRYPTION_KEY (base64 de 32 bytes)
openssl rand -base64 32

# Para EVOAI_CRM_API_TOKEN (UUID)
uuidgen
```

<Warning>
  Em produção, **nunca use os valores do `.env.example`**. Gere valores únicos para cada instalação.
  Todos os serviços que compartilham uma chave devem usar exatamente o mesmo valor.
</Warning>

***

## Frontend

As variáveis do frontend começam com `VITE_` e são incorporadas ao código no momento do build. Elas usam `localhost` porque o navegador as acessa diretamente — não pelo Docker.

```bash theme={null}
VITE_APP_ENV=development

# Endereços dos serviços (acessados pelo navegador)
VITE_API_URL=http://localhost:3000
VITE_AUTH_API_URL=http://localhost:3001
VITE_EVOAI_API_URL=http://localhost:5555
VITE_AGENT_PROCESSOR_URL=http://localhost:8000
```

Em produção, substitua `localhost` pelos domínios reais da sua instalação:

```bash theme={null}
VITE_APP_ENV=production
VITE_API_URL=https://api.seudominio.com
VITE_AUTH_API_URL=https://auth.seudominio.com
VITE_EVOAI_API_URL=https://core.seudominio.com
VITE_AGENT_PROCESSOR_URL=https://processor.seudominio.com
```

***

## E-mail (SMTP)

Em desenvolvimento, a plataforma usa o **Mailhog** — um servidor de e-mail local que captura as mensagens sem enviá-las de verdade. Acesse `http://localhost:8025` para ver os e-mails capturados.

```bash theme={null}
# Desenvolvimento com Mailhog (padrão — não precisa alterar)
SMTP_ADDRESS=mailhog
SMTP_PORT=1025
SMTP_DOMAIN=evoai-community.local
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=false
SMTP_USERNAME=
SMTP_PASSWORD=

MAILER_SENDER_EMAIL=noreply@evoai-community.local
```

Para produção, substitua pelos dados do seu provedor de e-mail:

```bash theme={null}
SMTP_ADDRESS=smtp.seudominio.com
SMTP_PORT=587
SMTP_DOMAIN=seudominio.com
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true
SMTP_USERNAME=noreply@seudominio.com
SMTP_PASSWORD=sua_senha_smtp

MAILER_SENDER_EMAIL=noreply@seudominio.com
```

### Configuração via UI em runtime (a partir do v1.0.0-rc3)

A partir do `v1.0.0-rc3` (EVO-1049), as configurações de SMTP, **BMS** e **Resend** podem ser alteradas via UI no painel `/settings/admin` e são aplicadas **em runtime**, sem reiniciar o container. Antes era necessário restart para que mudanças refletissem.

Isso significa que você pode:

* Manter `.env` apenas com defaults (ou nem configurar SMTP no `.env`, deixando vazio).
* Configurar credenciais de produção pela UI após o boot.
* Trocar provedor (de SMTP para Resend, por exemplo) sem downtime.

> O acesso ao painel `/settings/admin` é exclusivo do papel `super_admin` — o operador da instalação, separado do `account_owner`.

***

## Licensing e Operador

A partir do `v1.0.0-rc3`, o `.env.example` documenta a variável de operador:

```bash theme={null}
# E-mail do operador da instalação (usado em eventos de licensing)
EVOLUTION_OPERATOR_EMAIL=ops@seudominio.com
```

Este e-mail é referência para auto-ativação e telemetria. Para detalhes, ver [Licensing](/licensing).

***

## Canais opcionais

Essas variáveis ficam comentadas no `.env.example` e só precisam ser configuradas se você for usar os respectivos canais.

```bash theme={null}
# WhatsApp Cloud API
WP_APP_ID=seu_app_id
WP_VERIFY_TOKEN=seu_token_de_verificacao
WP_APP_SECRET=seu_app_secret

# Facebook Messenger
FB_APP_SECRET=seu_app_secret
FB_APP_ID=seu_app_id

# Google OAuth (integração com Gmail)
GOOGLE_OAUTH_CLIENT_ID=seu_client_id
GOOGLE_OAUTH_CLIENT_SECRET=seu_client_secret

# Slack
SLACK_CLIENT_ID=seu_client_id
SLACK_CLIENT_SECRET=seu_client_secret
```

***

## Dicas de segurança

* **Nunca envie o arquivo `.env` para o GitHub ou GitLab.** Ele já está no `.gitignore` por padrão.
* O arquivo `.env.example` é seguro para versionar — ele contém apenas exemplos sem dados reais.
* Em produção, gere valores únicos para `SECRET_KEY_BASE`, `JWT_SECRET_KEY`, `ENCRYPTION_KEY` e `EVOAI_CRM_API_TOKEN`.
* Use senhas fortes e únicas para `POSTGRES_PASSWORD` e `REDIS_PASSWORD`.

***

## Solução de problemas

### Banco de dados não conecta

Se após o `make setup` você vir erros de conexão:

1. Verifique se os containers estão rodando: `make status`
2. Confira os valores de `POSTGRES_HOST`, `POSTGRES_USERNAME` e `POSTGRES_PASSWORD` no `.env`
3. Para banco em nuvem, verifique se o acesso externo está liberado no painel do provedor

### E-mail não está sendo enviado

Em desenvolvimento, os e-mails não são enviados de verdade — ficam retidos no Mailhog. Acesse `http://localhost:8025` para visualizá-los.

### Serviço não sobe após o setup

```bash theme={null}
# Ver logs de um serviço específico
make logs SERVICE=evo-crm

# Ver todos os logs de uma vez
make logs
```

Os logs mostram exatamente qual variável está faltando ou com valor incorreto.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.