From 7a4979e0e11fc57d17d0628b35b95213201a20c5 Mon Sep 17 00:00:00 2001 From: Gustavo Date: Tue, 8 Sep 2026 18:20:03 -0300 Subject: [PATCH] chore: bootstrap MikroRMM local development baseline MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Baseline sobre upstream 2GT-Media-Group-LLC/mikrotik-manager @ 1a4b635 (v0.24.5-beta) - Adiciona docs/SISTEMA_ATUAL.md e CLAUDE.md (documentação operacional) - Ignora .secrets-local/ (nunca versionar secrets) Co-Authored-By: Claude Sonnet 5 --- .gitignore | 1 + CLAUDE.md | 24 ++++++++ docs/SISTEMA_ATUAL.md | 130 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 155 insertions(+) create mode 100644 CLAUDE.md create mode 100644 docs/SISTEMA_ATUAL.md diff --git a/.gitignore b/.gitignore index 50ac78a..8a3567a 100644 --- a/.gitignore +++ b/.gitignore @@ -145,3 +145,4 @@ vite.config.ts.timestamp-* # macOS .DS_Store site/ +.secrets-local/ diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..dce2944 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,24 @@ +# CLAUDE.md — MikroRMM + +Antes de alterar qualquer coisa neste projeto, leia nesta ordem: +1. Este arquivo (`CLAUDE.md`) +2. `docs/SISTEMA_ATUAL.md` +3. `git status` +4. `git log -5 --oneline` + +## Regras permanentes + +- Buscar causa-raiz antes de aplicar qualquer correção. +- Não alterar código sem entender o fluxo afetado. +- Preservar compatibilidade DEV/PROD (mesmo `docker-compose.yml` como base). +- Nunca versionar secrets. `.env` e `.secrets-local/` ficam fora do Git. +- Mudança de schema exige migration (`backend/src/db/migrate.ts`), nunca alteração manual do banco. +- Testes focados primeiro (teste/módulo afetado), depois suíte completa como gate final. +- Smoke real (`docker compose ps` + `curl https://localhost/api/health`) quando a mudança afetar runtime. +- Atualizar `docs/SISTEMA_ATUAL.md` quando a mudança alterar arquitetura ou estado de verdade do sistema (não é changelog). +- Não executar ações destrutivas em RouterBOARD sem missão explícita autorizando. +- Não conectar clientes reais durante desenvolvimento. +- Não considerar uma missão concluída com Git sujo (`git status` deve estar limpo, salvo arquivos intencionalmente não commitados e justificados). + +## Ambiente local +Ver seção 12 de `docs/SISTEMA_ATUAL.md`. Stack sobe com `docker compose up -d` a partir de `docker-compose.yml` (build local, não usar `docker-compose.ghcr.yml` em DEV). diff --git a/docs/SISTEMA_ATUAL.md b/docs/SISTEMA_ATUAL.md new file mode 100644 index 0000000..e9dc47c --- /dev/null +++ b/docs/SISTEMA_ATUAL.md @@ -0,0 +1,130 @@ +# MikroRMM — Sistema Atual + +## 1. Objetivo do sistema +Plataforma de gestão e monitoramento de dispositivos MikroTik (RouterOS): inventário de clientes/dispositivos, polling de métricas, backups, automação, alertas, change guard, firmware rollout, topologia de rede. + +## 2. Base upstream +- Projeto: MikroTik Manager (2GT Media Group LLC) +- Repositório: https://github.com/2GT-Media-Group-LLC/mikrotik-manager +- Licença: ver `LICENSE` na raiz do repo +- Remote local: `origin` → https://github.com/2GT-Media-Group-LLC/mikrotik-manager.git +- Commit baseline: `1a4b6350528b8c656ab7a84ee4806a8a86cf9932` (branch `main`, tag semântica v0.24.5-beta) +- Branch de trabalho MikroRMM: `mikrormm-dev` + +## 3. Arquitetura atual +Stack Docker Compose com 5 serviços: `nginx` (proxy/reverse proxy + estáticos do frontend), `backend` (API Node/Express + poller + coletor NetFlow), `postgres` (dados relacionais), `redis` (filas BullMQ), `influxdb` (métricas de série temporal). + +## 4. Estrutura do repositório +- `backend/` — API Node.js/TypeScript (Express, BullMQ, Socket.IO, SSH2) +- `frontend/` — SPA React 19 + Vite + TailwindCSS +- `nginx/` — Dockerfile, `nginx.conf`, `entrypoint.sh` (gera cert self-signed se ausente) +- `docs/` — documentação (mkdocs) +- `scripts/` — utilitários e fixtures de seed + +## 5. Containers e serviços +| Serviço | Imagem | Porta host (DEV) | Healthcheck | +|----------|-----------------------|------------------------|-------------| +| nginx | build local | 80, 443 | nenhum definido no compose | +| backend | build local | 2055/udp (NetFlow) | `GET /api/health` | +| postgres | postgres:15-alpine | interno | `pg_isready` | +| redis | redis:7-alpine | interno | `redis-cli ping` | +| influxdb | influxdb:2.7 | interno | `influx ping` | + +## 6. Banco de dados +PostgreSQL 15, banco `mikrotik_manager`, usuário `mikrotik`. Migrations em `backend/src/db/migrate.ts`, executadas automaticamente no boot do backend (idempotente — cria usuário admin default apenas se a tabela `users` estiver vazia). + +## 7. Redis / filas +BullMQ para jobs de polling/automação. `maxmemory` configurável via `REDIS_MAXMEMORY` (default 512mb), política `noeviction` (ver comentário no `docker-compose.yml`). + +## 8. InfluxDB / métricas +InfluxDB 2.7, org/bucket configuráveis via env (`INFLUXDB_ORG`, `INFLUXDB_BUCKET`), token de admin gerado no setup inicial. + +## 9. Frontend +React 19 + Vite + TailwindCSS, servido como estático pelo nginx. Build gera chunk principal >500KB (aviso do Vite, não bloqueante). + +## 10. Backend +Node.js/TypeScript, Express, autenticação JWT, TOTP opcional, OIDC opcional, coletor NetFlow/IPFIX na porta 2055/udp, backups, SSH (ssh2) para RouterOS. + +## 11. Autenticação +JWT (`JWT_SECRET`), senha com bcryptjs, suporte a TOTP e OIDC. Usuário admin default criado na migration inicial (`admin/admin`) — **a senha padrão DEVE ser trocada imediatamente após o primeiro login** (feito nesta instalação DEV; ver seção 12 do CLAUDE.md). + +## 12. Ambiente DEV +- Diretório: `D:\PROJETOS\MIKROTIK RMM\mikrormm` (Windows 11, Git Bash/MINGW64) +- Docker: 29.6.2 / Compose v5.3.1 +- Compose usado: `docker-compose.yml` (build local a partir do código-fonte, não `docker-compose.ghcr.yml`) +- Portas publicadas: 80 (HTTP), 443 (HTTPS self-signed), 2055/udp (NetFlow) +- `.env` local com secrets DEV gerados aleatoriamente (nunca versionado) +- `TZ=America/Bahia` + +## 13. Ambiente PROD planejado +Infraestrutura Docker dedicada da GTI. Deve manter paridade com DEV (mesmo `docker-compose.yml` como base, variando apenas `.env`/secrets/domínio/CORS). Não implementado nesta missão. + +## 14. Variáveis de ambiente +Somente nomes e finalidade (ver `.env.example` para a lista completa): +- `HTTP_PORT`, `HTTPS_PORT` — portas publicadas do nginx +- `TZ` — timezone dos containers +- `CORS_ORIGIN` — origens permitidas pela API +- `DB_PASSWORD` — senha do PostgreSQL +- `JWT_SECRET` — segredo de assinatura JWT +- `ENCRYPTION_KEY` — chave de criptografia de senhas de dispositivos (32 bytes) +- `INFLUXDB_TOKEN`, `INFLUXDB_ORG`, `INFLUXDB_BUCKET`, `INFLUXDB_ADMIN_PASSWORD` — InfluxDB +- `POLLER_*` — tuning do poller de dispositivos +- `REDIS_MAXMEMORY` — teto de memória do Redis + +## 15. Como iniciar +```bash +docker compose up -d +``` + +## 16. Como parar +```bash +docker compose down +``` + +## 17. Como rebuildar +```bash +docker compose build +docker compose up -d +``` + +## 18. Como verificar saúde +```bash +docker compose ps +curl -k https://localhost/api/health +``` + +## 19. Como executar testes +```bash +# backend +cd backend && npm ci && npm test && npm run lint && npx tsc --noEmit +# frontend +cd frontend && npm ci && npm test -- --run && npm run lint && npm run build +``` + +## 20. Persistência e volumes +Volumes nomeados: `postgres_data`, `redis_data`, `influxdb_data`, `backups_data`, `certs_data`, `app_data`. Persistência comprovada via `docker compose restart` nesta missão. + +## 21. Backup do próprio MikroRMM +Backend expõe rotas de backup de dispositivos (`backups_data`); backup do próprio stack MikroRMM (dump de `postgres_data`/`influxdb_data`) ainda não documentado/procedimentado — pendente de missão futura. + +## 22. Segurança atual +- `.env` fora do Git (confirmado via `git check-ignore`) +- Secrets DEV gerados aleatoriamente (DB_PASSWORD 32c, JWT_SECRET 64c hex, ENCRYPTION_KEY 32c, INFLUXDB_TOKEN 64c hex, INFLUXDB_ADMIN_PASSWORD 24c) +- Senha padrão do admin alterada (ver `.secrets-local/dev-admin-password.txt`, fora do Git) +- Certificado HTTPS self-signed gerado pelo nginx (`nginx/entrypoint.sh`) — adequado só para DEV +- Lint de segurança (`eslint-plugin-security`) roda no baseline com 270 (backend) + 108 (frontend) warnings, 0 erros — não corrigido nesta missão (fica para auditoria) + +## 23. Integrações atuais +Nenhuma integração externa real conectada (GLPI, Slack, SFTP, RouterBOARD real) — fora do escopo desta missão. + +## 24. Funcionalidades atualmente disponíveis +Conforme upstream v0.24.5-beta: gestão de clientes/dispositivos, polling, backups, automação, alertas, change guard, firmware rollout, topologia, NetFlow, OIDC, TOTP. Ver `README.md` do upstream para detalhes completos. + +## 25. Funcionalidades GTI ainda não implementadas +Integração GLPI, SFTP, Slack, onboarding customizado, renomeação para "MikroRMM", RouterBOARD real conectada. + +## 26. Procedimento para mudanças com IA +Ver `CLAUDE.md` na raiz do projeto. + +## 27. Prompt/missão operacional atual +**Missão 00 — Preparar Ambiente Dev Local** (concluída): bootstrap e baseline apenas. Clonar upstream, subir stack local via build de código-fonte, validar saúde/login/testes, documentar, manter Git limpo, zero secrets versionados. Proibido nesta missão: renomear o produto, redesenhar UI, implementar GLPI/SFTP/Slack, alterar autenticação/schema/Change Guard, conectar RouterBOARD real, corrigir achados de auditoria. Próxima missão recomendada: **Auditoria Técnica e de Segurança da Base Upstream**.