# Runbook — Crash loop por ausência de symlink `.env`

Última atualização: 20/08/2026 · Origem: `docs/SESSIONS/2026-08-19/`

## Sintoma

Containers `evo-bot-runtime`, `evo-core` e `evo-processor` em crash loop
tentando conectar em `localhost` no lugar do host Redis real.

## Causa raiz

O `docker-compose.yml` usa interpolação `${REDIS_PASSWORD}@${REDIS_HOST}`
diretamente no bloco `environment:`. Essa interpolação só é resolvida a
partir de um arquivo `.env` na raiz do projeto — **não** a partir de
`env_file:`, que só injeta variáveis dentro do container, sem alimentar a
interpolação do próprio `docker-compose.yml`.

No servidor, só existia `.secrets/.env` (usado via `env_file:`), sem o
`.env` na raiz. Resultado: `REDIS_URL=redis://:@:6379` — string vazia
interpolada, containers tentando `localhost`.

## Correção

Criar um symlink `.env` → `.secrets/.env` na raiz do projeto no servidor:

```bash
ln -s .secrets/.env .env
```

## Validação

1. Recriar os containers afetados (`docker compose up -d`).
2. Confirmar nos logs que a conexão Redis usa o host correto (sem expor a senha nos logs).
3. Containers saem do estado de restart loop e ficam `healthy`.

## Prevenção

Sempre que uma variável for referenciada diretamente em `environment:` (não
só via `env_file:`), garantir que o `.env` na raiz do projeto — seja
arquivo real ou symlink — está presente antes do `docker compose up`. Ver
[Variáveis de ambiente](../deploy/variaveis-de-ambiente.md).