Estrutura de Diretórios e Modelo de Execução¶

Status¶

Aprovado

Contexto¶

A estrutura de /opt/pagesaude cresceu sem um critério registrado, gerando dúvidas recorrentes:

se a raiz /opt/pagesaude continua adequada ou se deveríamos usar diretórios padrão do sistema operacional (/srv, /var/lib, /var/log);
onde aplicações devem ficar em relação aos serviços de infraestrutura compartilhados;
se diretórios dedicados de logs, data, storage, volumes, scripts e backups devem existir;
qual componente deve rodar como container Docker e qual deve rodar direto no sistema operacional via systemd.

Sem esse critério escrito, cada novo serviço foi provisionado por analogia, o que dificulta a evolução e a automação.

Decisão¶

Raiz e organização¶

Manter /opt/pagesaude como raiz do que este repositório provisiona, com três diretórios:

/opt/pagesaude
├── apps/       # aplicações de negócio (webapps, workers)
├── services/   # infraestrutura compartilhada (banco, cache, proxy, observabilidade)
└── secrets/    # segredos gerados pelo provisionamento, fora do versionamento

Aplicações e serviços de infraestrutura permanecem separados por diretório, mas na mesma raiz: o ciclo de vida dos dois é gerenciado pelo mesmo provisionamento, e separá-los em raízes diferentes só aumentaria o número de caminhos a manter.

/opt é adequado porque todo o conteúdo é software adicional, autocontido e gerenciado por esta automação — exatamente o propósito do diretório no FHS. Migrar para /srv e /var/lib espalharia um conjunto coeso por vários pontos do sistema, exigiria migração de dados em produção e não traria ganho operacional.

Logs e dados¶

Logs: apenas stdout/stderr. A coleta é feita pelo Alloy via socket do Docker, com rotação configurada no próprio compose (logging.options). Não criar diretórios de log por aplicação nem montar /logs.
Dados persistentes: volumes Docker nomeados, declarados no compose.yaml do serviço. Não criar /data, /storage ou /volumes manualmente no host.
Backups: permanecem sob o fluxo do serviço de backup do PostgreSQL (services/database/postgres/backup/), não em diretório solto no host.

Container ou systemd¶

Executar via	Critério	Exemplos
systemd (host)	O componente precisa existir antes ou independentemente do Docker	Docker engine, `sshd`, agente do provedor, cron do host
Container	Todo o resto	aplicações, PostgreSQL, Redis, Traefik, stack de observabilidade, Portainer

A regra prática: se o componente é pré-requisito para rodar containers, ele é do sistema operacional; se ele pode ser expresso como um compose.yaml versionado neste repositório, ele é container.

Consequências¶

A estrutura atual é preservada; não há migração de dados nem janela de indisponibilidade.
Novos serviços têm um lugar previsível e um critério objetivo de execução.
Aplicações que hoje gravam log em arquivo precisam migrar para stdout ao serem integradas — a coleta não lê arquivos dentro de containers.
Serviços que exigirem estado no host (fora de volume Docker) passam a ser exceção e precisam de justificativa registrada em nova ADR.