Variáveis de Ambiente - Documentação do Evolution Foundation

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:

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.

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.

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.

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

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:

POSTGRES_CONNECTION_STRING=postgresql://postgres:sua_senha_segura@postgres:5432/evo_community

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.

Redis (cache e filas)

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

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

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

# 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

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.

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.

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:

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.

# 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=[email protected]

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

SMTP_ADDRESS=smtp.seudominio.com
SMTP_PORT=587
SMTP_DOMAIN=seudominio.com
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true
SMTP_USERNAME=[email protected]
SMTP_PASSWORD=sua_senha_smtp

MAILER_SENDER_EMAIL=[email protected]

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:

# E-mail do operador da instalação (usado em eventos de licensing)
EVOLUTION_OPERATOR_EMAIL=[email protected]

Este e-mail é referência para auto-ativação e telemetria. Para detalhes, ver Licensing.

Canais opcionais

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

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

Verifique se os containers estão rodando: make status
Confira os valores de POSTGRES_HOST, POSTGRES_USERNAME e POSTGRES_PASSWORD no .env
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

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

​Como funciona

​Banco de dados (PostgreSQL)

​Redis (cache e filas)

​Secrets compartilhados

​Frontend

​E-mail (SMTP)

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

​Licensing e Operador

​Canais opcionais

​Dicas de segurança

​Solução de problemas

​Banco de dados não conecta

​E-mail não está sendo enviado

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

Como funciona

Banco de dados (PostgreSQL)

Redis (cache e filas)

Secrets compartilhados

Frontend

E-mail (SMTP)

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

Licensing e Operador

Canais opcionais

Dicas de segurança

Solução de problemas

Banco de dados não conecta

E-mail não está sendo enviado

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