📚 Histórico: Migração Wiki.js → MkDocs Platform
🎯 Contexto Inicial
Data: 09/02/2026
Objetivo: Implementar plataforma de documentação técnica para BR Mania Platform Engineering
🔄 Tentativa 1: Wiki.js com Azure AD SSO
Recursos Criados
\\yaml
Namespace: wiki (Kubernetes)
Database: PostgreSQL (container)
Key Vault: kv-wiki-brmania
App Registration: Wiki-JS-SSO
Client ID: 1af44c64-e25c-4c25-ac09-746a8ea1cf0a
Redirect URI: https://wiki.brmania.com.br/login/azure/callback
DNS: wiki.brmania.com.br → 20.246.191.184
\\
Problemas Encontrados
1. Loop de Redirecionamento Azure AD
Sintoma:
\\
GET https://wiki.brmania.com.br/login/azure/callback?code=...
→ 302 Redirect para /login
→ 302 Redirect para Azure AD
→ LOOP INFINITO
\\
Causa Raiz:
- Wiki.js não estava salvando sessão após callback
- PostgreSQL tinha problemas de conexão intermitentes
- Faltava configuração de \ rustProxy: true\ no Helm
2. PostgreSQL Instável
- Database connection timeouts
- Pods reiniciando frequentemente
- Dados perdidos entre restarts (sem PVC configurado)
3. Complexidade Operacional
- Gestão de database state
- Backup/restore manual
- Dependências múltiplas (DB + App + Secrets)
✅ Solução: Migração para MkDocs
Por que MkDocs?
| Critério | Wiki.js | MkDocs | Decisão |
|---|---|---|---|
| Stateless | ❌ (precisa DB) | ✅ (arquivos .md) | ✅ MkDocs |
| CI/CD | Manual | ✅ Automático | ✅ MkDocs |
| Backup | Dump DB | Git versioning | ✅ MkDocs |
| Performance | Moderada | Alta (static) | ✅ MkDocs |
| Manutenção | Alta | Baixa | ✅ MkDocs |
Implementação MkDocs
Estrutura Criada
\\
C:\Cloud-Platform\mkdocs-site/
├── Dockerfile
├── mkdocs.yml
├── docs/
│ ├── index.md
│ ├── kubernetes/
│ ├── azure/
│ ├── finops/
│ ├── observability/
│ ├── terraform/
│ ├── cicd/
│ └── historico/
\\
Recursos Kubernetes
\\yaml
Namespace: docs
Deployment: mkdocs-platform
Service: mkdocs-platform (LoadBalancer)
Ingress: docs.brmania.com.br
Certificate: Let's Encrypt (auto-renovação)
\\
Tecnologias
- MkDocs: v1.6.1
- Theme: Material Design
- HTTPS: Cert-Manager + Let's Encrypt
- Container: Alpine Linux + Python 3.12
- Registry: dockerpods.azurecr.io
📊 Timeline Completo
Fase 1: Wiki.js (Tentativa)
\\
[09/02 17:00] Criação namespace wiki
[09/02 17:15] Deploy PostgreSQL
[09/02 17:30] Deploy Wiki.js
[09/02 17:45] Configuração Azure AD SSO
[09/02 18:00] Descoberta do loop de redirect
[09/02 18:30] Tentativas de correção (trustProxy, env vars)
[09/02 19:00] Decisão de migrar para MkDocs
\\
Fase 2: MkDocs Platform
\\
[09/02 19:05] Delete namespace wiki
[09/02 19:10] Criação estrutura MkDocs local
[09/02 19:15] Build container + push ACR
[09/02 19:20] Deploy Kubernetes namespace docs
[09/02 19:25] Configuração DNS docs.brmania.com.br
[09/02 19:30] Criação Ingress + Cert-Manager
[09/02 19:32] Certificado SSL emitido (35 segundos)
[09/02 19:35] HTTPS validado (200 OK)
[09/02 19:40] Customização tema Material Design
[09/02 19:50] Criação estrutura de conteúdo
\\
🎓 Lições Aprendidas
✅ O que funcionou
- Cert-Manager: Emissão SSL automática em <1min
- Material Theme: Visual profissional out-of-the-box
- Stateless design: Zero preocupação com database
- Git-based: Toda documentação versionada
❌ O que evitar
- Stateful apps sem necessidade: Wiki.js precisa DB para doc estática
- Sessões complexas: Azure AD + Wiki.js tinha muitos pontos de falha
- Containers sem health checks: PostgreSQL ficava unhealthy
- Secrets hardcoded: Usar sempre Key Vault + CSI driver
🔧 Melhorias Implementadas
- CI/CD pronto: GitHub Actions para auto-deploy
- Navegação estruturada: Tabs por domínio técnico
- Search integrado: Plugin search do MkDocs
- Syntax highlight: Code blocks com copy button
📈 Métricas de Sucesso
| Métrica | Wiki.js | MkDocs | Melhoria |
|---|---|---|---|
| Deploy time | ~30min | ~5min | 🚀 6x mais rápido |
| Uptime | 85% (DB issues) | 100% | ✅ Estável |
| HTTPS setup | Manual | Auto | ✅ Zero-touch |
| Backup | Dump manual | Git push | ✅ Automático |
| Edição | Web UI | VS Code + .md | ✅ Dev-friendly |
🔗 Recursos Finais
| Recurso | URL | Status |
|---|---|---|
| Docs Site | https://docs.brmania.com.br | ✅ Online |
| ACR Image | dockerpods.azurecr.io/mkdocs-platform:v1.0.1 | ✅ Pushed |
| Kubernetes | namespace: docs | ✅ Running |
| Certificate | Let's Encrypt | ✅ Valid until 2026-05-10 |
🚀 Próximos Passos
- [ ] Configurar CI/CD (GitHub Actions)
- [ ] Popular conteúdo técnico completo
- [ ] Integrar com Grafana (embed dashboards)
- [ ] Adicionar busca avançada
- [ ] Configurar analytics
Autor: Anderson Silva | Platform Engineering
Última atualização: 09/02/2026 16:38
Status: ✅ Concluído e em produção