Problema

En cualquier homelab que haya crecido más allá de un par de contenedores, la información se dispersa: una hoja de cálculo con puertos, un archivo markdown con direcciones IP, diagramas dibujados en papel y notas sueltas en la nube. Cuando se necesita añadir una nueva VM, cambiar un puerto o migrar un disco, la falta de una “única fuente de verdad” obliga a buscar en varios lugares, y el riesgo de colisión o de olvidar una dependencia aumenta rápidamente. El síntoma típico es una tabla de puertos desactualizada, una IP asignada dos veces o un diagrama que no refleja la topología real.

Causa

  1. Herramientas aisladas – Cada pieza de información se guarda en la herramienta que mejor se adapta al momento (Google Sheets para puertos, Notion para diagramas, etc.). No hay un modelo de datos compartido.
  2. Actualizaciones manuales – Cada cambio requiere editar varios documentos de forma independiente; la automatización rara vez está presente.
  3. Falta de esquema – Sin una estructura clara (por ejemplo, “VM → recursos → puertos → IP”), los usuarios crean páginas ad‑hoc que no se enlazan entre sí.
  4. Escalado inesperado – Lo que empezó como un único nodo con unas cuantas LXCs se vuelve un cluster de VMs; la solución original no está preparada para crecer y se vuelve frágil.

Solución

Una solución reutilizable combina tres capas:

Capa Función Herramientas recomendadas
Wiki central Almacena documentación estructurada, permite exportar a PDF y soporta diagramas incrustados. BookStack (Docker), Wiki.js (Git‑backed)
IPAM/Port‑matrix Gestiona direcciones IP, bloques CIDR y asignaciones de puertos. NetBox (full‑featured), phpIPAM (ligero), tablas markdown para laboratorios muy pequeños
Automatización de export Genera PDFs o artefactos estáticos de forma periódica y los respalda en Git. wkhtmltopdf + script Bash, GitHub Actions (si se usa Wiki.js)

1. Configurar la wiki

BookStack es fácil de lanzar con Docker y ya incluye integración nativa de draw.io. La estructura típica es:

  • Libro “Infraestructura”
    • Capítulo “Máquinas virtuales”
      • Página “Talos – Docker Hub” (tabla de recursos, puertos, IP)
    • Capítulo “Red”
      • Página “Mapa de red” (draw.io embed)
    • Capítulo “IPAM”
      • Página “Bloques CIDR” (tabla markdown)

Si prefieres un backend Git, Wiki.js ofrece edición markdown, control de versiones y plugins para diagramas PlantUML o Mermaid. La ventaja es que cada página es un archivo en el repositorio, lo que simplifica los backups.

2. Añadir IPAM y port‑matrix

Para un homelab de una sola máquina, una tabla markdown bien mantenida puede ser suficiente:

| Servicio            | IP interna | Puerto externo | VM/LXC |
|---------------------|------------|----------------|--------|
| Home Assistant      | 10.0.0.10  | 8123           | Talos  |
| AdGuard Home        | 10.0.0.20  | 53, 443        | Argus  |
| Prometheus          | 10.0.0.30  | 9090           | Helios |

Cuando el número de entradas supera 30‑40, la gestión manual se vuelve propensa a errores. En ese punto, despliega NetBox (Docker o VM) y usa su API para rellenar la tabla de la wiki automáticamente mediante un pequeño script o un webhook de tu orquestador (por ejemplo, Ansible). NetBox también permite marcar puertos como “reserved”, evitando colisiones.

3. Automatizar la exportación

BookStack permite exportar un libro completo a PDF desde la UI, pero para mantener versiones históricas se recomienda un script que:

  1. Descargue el HTML del libro mediante la API.
  2. Convierta el HTML a PDF con wkhtmltopdf.
  3. Commit y push al repositorio de backups.
#!/usr/bin/env bash
API_TOKEN="YOUR_BOOKSTACK_TOKEN"
BOOK_ID=5
TMP_DIR=$(mktemp -d)

curl -s -H "Authorization: Token $API_TOKEN" \
     "https://bookstack.local/api/books/$BOOK_ID/export/html" \
     -o "$TMP_DIR/book.html"

wkhtmltopdf "$TMP_DIR/book.html" "backup/homelab_$(date +%F).pdf"

git -C backup add .
git -C backup commit -m "Backup PDF $(date +%F)"
git -C backup push

En Wiki.js, la exportación a PDF se puede orquestar con GitHub Actions que ejecuten pandoc sobre los archivos markdown.

4. Integrar diagramas dinámicos

Draw.io dentro de BookStack guarda los diagramas como archivos XML en la base de datos; al exportar a PDF el diagrama se renderiza automáticamente. En Wiki.js, usa Mermaid o PlantUML y habilita la opción “render on build” para que los diagramas se incluyan en el PDF generado por pandoc.

5. Copias de seguridad y versionado

  • Wiki: habilita snapshots diarios (Docker docker commit o snapshots de la VM).
  • IPAM: NetBox tiene exportación JSON; programa un cron que lo guarde en el mismo repositorio.
  • Datos estáticos: los PDFs generados se versionan junto al código, lo que permite comparar cambios con git diff.

Cuándo aplicar esta solución

  • Homelabs con >5 servicios que requieren puertos fijos y asignaciones IP estáticas.
  • Entornos que crecen (añaden VMs, contenedores o discos) y necesitan una visión consolidada.
  • Necesidad de exportar documentación para auditorías, presentaciones o simplemente para leer offline.

No es necesario desplegar NetBox si el número de IP/puertos es inferior a 20 y no se espera expansión; una tabla markdown en la wiki basta. Por otro lado, si el homelab evoluciona a un cluster Kubernetes con varios nodos, la combinación wiki + NetBox puede quedarse corta y será más apropiado migrar a una solución de CMDB completa.

Código

#!/usr/bin/env bash
# Exportar un libro de BookStack a PDF y guardarlo en Git
API_TOKEN="REPLACE_WITH_TOKEN"
BOOK_ID=3
OUT_DIR="/opt/homelab-docs/backups"
mkdir -p "$OUT_DIR"

# 1. Obtener HTML del libro
curl -s -H "Authorization: Token $API_TOKEN" \
     "https://bookstack.local/api/books/$BOOK_ID/export/html" \
     -o "$OUT_DIR/book.html"

# 2. Convertir a PDF
wkhtmltopdf "$OUT_DIR/book.html" "$OUT_DIR/homelab_$(date +%F).pdf"

# 3. Commit en Git
git -C "$OUT_DIR" add .
git -C "$OUT_DIR" commit -m "Backup PDF $(date +%F)"
git -C "$OUT_DIR" push

Verificación

  1. Consistencia de puertos – Ejecuta netstat -tulnp en cada VM/LXC y compara la salida con la tabla de la wiki.
  2. IP duplicadas – Usa nmap -sn 10.0.0.0/24 y verifica que cada IP listada en NetBox aparece una sola vez.
  3. Diagramas – Abre el PDF exportado y comprueba que los diagramas draw.io/mermaid se renderizan sin errores.
  4. Backup – Revisa que el último commit en el repositorio contiene el PDF y los archivos JSON de NetBox.

Notas adicionales

  • Nomenclatura: adopta un esquema de nombres coherente (p.ej., VM‑<nombre‑mitológico>); facilita búsquedas y evita colisiones.
  • Bloques CIDR: reserva bloques /24 por zona (p.ej., 10.0.1.0/24 para servidores, 10.0.2.0/24 para cont