# ADR-006 — Arquivos por bind mount local (layout padrão do WHM)

| Campo | Valor |
|---|---|
| **Status** | Aceito (2026-10-16) |
| **Data** | 2026-10-14 |
| **Plano de origem** | `wiki/plan/01-analise-e-decisoes.md` |
| **Relacionadas** | ADR-005, ADR-007, ADR-008, ADR-030 |

## Contexto

O operacional do servidor é `git clone --depth=1` em **`/home/<tenant>/public_html`**, e o
WHM/cPanel age sobre essa pasta (ADR-005). O bind mount precisa **preservar esse layout** para
não criar atrito, e ao mesmo tempo manter o **storage** local e simples — com a possibilidade de
movê-lo para um disco mais rápido/maior quando o volume exigir.

## Decisão

- O repositório é montado nos containers como **`/var/www/html:Z`**:
  - **Dev:** diretório do programador.
  - **Prod:** `/home/<tenant>/public_html` (o próprio local do `git clone`).
- **Storage local (framework), com caminho configurável:**
  - **Padrão (zero atrito):** `public_html/storage` → `/var/www/html/storage`.
  - **Opcional (`STORAGE_PATH`):** apontar para um disco **fora da cota** (ex.: `/srv/...`),
    bind-montado **sobre** `public_html/storage`. O Laravel não percebe a diferença.
  - `storage/` guarda **logs, sessões, cache, framework e tmp de upload** — **não** é a base da
    mídia.
- **Mídia/anexos em object storage S3** (ADR-030): o serviço **`storage` (RustFS)** guarda
  `${DATA_PATH}/rustfs/data` — default `./s3-local` **dentro do repositório** (ignorado pelo git);
  em produção aponte `DATA_PATH` para fora da cota. Troca por **AWS S3** só com `.env`.
- UID/GID alinhados ao usuário non-root da imagem; `storage/` gravável pelo FPM.
- `DocumentRoot` do app é `public/`, servido **pelo container** (`web`), não pelo Apache do WHM.
- OPcache em produção (`validate_timestamps=0`); `./up_prod.sh` (ou `make reload`) recarrega.
- Arquivos do cPanel (`.user.ini`, `php.ini`, `.htaccess`, `error_log`) ficam no mount, mas são
  **ignorados por configuração** (ADR-005) — não entram em `.gitignore` de forma destrutiva, mas
  **não** são versionados.

## Justificativa (alternativas descartadas)

- **App fora do docroot** — descartada: atrito operacional (equipes clonam em `public_html`).
- **Storage obrigatoriamente fora da home** — descartada como padrão: o caminho local
  `public_html/storage` é o mais simples; a opção `STORAGE_PATH` cobre o caso de volume/cota.
- **Volumes nomeados/anônimos para o código** — descartada: backup/inspeção difíceis.
- **Copiar código para a imagem** — descartada: rebuild a cada mudança.
- **Sem `:Z`** — descartada: quebra em hosts com SELinux.

## Consequências

**Positivas**
- Layout do WHM intacto; edição/backup do código direto no host.
- Storage simples por padrão e **relocável** quando necessário.
- Deploy = `git pull` em `public_html` + `./up_prod.sh` (plan 15).

**Custos / negativas**
- O mount contém artefatos do cPanel; a mitigação é a configuração de "ignorar" (ADR-005).
- Performance de I/O em macOS/Windows pode exigir tuning; OPcache precisa de reload.

## Exemplo mínimo (comparativo)

```yaml
# ✅ Layout padrão + storage relocável + object storage S3 local (RustFS)
services:
  php-fpm:
    volumes:
      - /home/<tenant>/public_html:/var/www/html:Z
      - ${STORAGE_PATH:-./storage}:/var/www/html/storage:Z
  storage:
    image: rustfs/rustfs:1.0.1-glibc@sha256:87763ed4dcb2bed3fc52cbf6cb7d865411e085b0b952dc78e50dffa9ece0ed9e
    volumes:
      - ${DATA_PATH:-./s3-local}/rustfs/data:/data
      # sem `ports:` (rede internal)
```

## Verificação

- `make down && make up` (dev) e `./up_prod.sh` (prod) preservam dados e recriam serviços.
- Editar um arquivo no host reflete no container (com reload de OPcache).
- `STORAGE_PATH` apontando para outro disco mantém a app funcionando sem mudança de código.
- `DATA_PATH/rustfs/data` guarda os objetos; trocar por AWS S3 é **só `.env`** (ADR-030).
- `docker compose exec php-fpm ls -la /var/www/html` mostra os arquivos do cPanel presentes,
  porém **inertes** (`.user.ini` ignorado, `.htaccess` não lido).

## Referências

- `wiki/plan/04-runtime-containers.md`; `wiki/adr/ADR-005-runtime-containers-edge-apache-whm.md`.