ADR-004: Portal de Documentação MkDocs¶

Status: Implementado | Data: 2026-02-08 | Autor: Werner (CTO)

Contexto¶

A documentação do APEX estava dispersa em arquivos markdown sem uma interface de visualização. Era necessário:

Portal web para visualizar documentação
Acesso protegido (não público)
Anti-indexação (não aparecer no Google)
Compatibilidade com 1Password
Isolamento do domínio principal da empresa

Decisão¶

Implementar MkDocs com Material theme servido via nginx com Basic Auth.

Arquitetura¶

┌─────────────────────────────────────────────────────────────┐
│                    FLUXO DE DOCUMENTAÇÃO                    │
│                                                             │
│  /apex/core/governance/*.md                                │
│  /apex/*/DOCS/*.md                                         │
│         │                                                   │
│         ▼                                                   │
│  /root/clawd/docs-site/docs/    (fonte MkDocs)             │
│         │                                                   │
│         ▼  [mkdocs build]                                  │
│  /var/www/arcos-docs/           (site estático)            │
│         │                                                   │
│         ▼                                                   │
│  nginx :8080 + Basic Auth                                  │
│         │                                                   │
│         ▼                                                   │
│  http://arcos:***@216.238.121.209:8080                     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Componentes¶

1. MkDocs + Material Theme¶

Instalação:

pip install mkdocs mkdocs-material

Configuração: /root/clawd/docs-site/mkdocs.yml

site_name: APEX - Documentação
theme:
  name: material
  language: pt-BR
plugins:
  - search

2. Estrutura de Diretórios¶

/root/clawd/docs-site/
├── mkdocs.yml              # Configuração
└── docs/
    ├── index.md            # Home
    ├── infra/              # Infraestrutura
    │   └── migracao-claudecode-moltbot.md
    ├── apex/               # Agentes APEX
    │   └── visao-geral.md
    └── operacoes/          # Operações
        └── comandos-gateway.md

3. Nginx + Basic Auth¶

Configuração: /etc/nginx/sites-available/arcos-docs

server {
    listen 8080;
    root /var/www/arcos-docs;

    auth_basic "APEX Docs";
    auth_basic_user_file /etc/nginx/.htpasswd;

    add_header X-Robots-Tag "noindex, nofollow" always;
}

Credenciais: /etc/nginx/.htpasswd - Usuário: arcos - Senha: (armazenada em hash)

4. Script de Deploy¶

Localização: /root/clawd/scripts/deploy-docs.sh

#!/bin/bash
cd /root/clawd/docs-site
mkdocs build
cp -r site/* /var/www/arcos-docs/
chown -R www-data:www-data /var/www/arcos-docs

Segurança¶

Medida	Implementação
Autenticação	Basic Auth obrigatório
Anti-indexação	robots.txt + X-Robots-Tag header
Isolamento	Porta 8080, sem domínio público
Firewall	UFW permite apenas 8080

Acesso¶

URL: http://arcos:<senha>@216.238.121.209:8080

Recomendação: Salvar URL completa no 1Password para acesso direto.

Alternativas Consideradas¶

Opção	Por que não
GitHub Pages	Público, sem auth nativa
BookStack	Mais pesado, requer manutenção
Notion	SaaS pago, dados externos
Google OAuth	Requer HTTPS + domínio próprio
Cloudflare Tunnel	Complexidade adicional

Fluxo de Atualização¶

Editar/criar .md no APEX (fonte da verdade)
Copiar para /root/clawd/docs-site/docs/
Executar ./scripts/deploy-docs.sh
Site atualizado automaticamente

Comandos Úteis¶

# Rebuild e deploy
./scripts/deploy-docs.sh

# Preview local (porta 8000)
cd /root/clawd/docs-site && mkdocs serve

# Verificar nginx
nginx -t && systemctl reload nginx

# Alterar senha
htpasswd /etc/nginx/.htpasswd arcos

Dependências¶

Python 3.x
mkdocs >= 1.6
mkdocs-material >= 9.7
nginx
Porta 8080 aberta no firewall

Histórico¶

Data	Evento
2026-02-08	Implementação inicial
2026-02-08	Tentativa OAuth (falhou - requer HTTPS)
2026-02-08	Rollback para Basic Auth

Documento criado seguindo APEX Governance