Documentar un homelab suena a tarea gris. De esas que uno deja para “cuando esté todo ordenado”, que es una forma muy educada de decir nunca. Es mucho más divertido montar otro servicio, probar una versión nueva de Proxmox, cambiar el reverse proxy o comprar un mini PC que estaba demasiado barato para dejarlo pasar.
El problema es que el homelab tiene memoria de pez si no escribes las cosas. Tú crees que te vas a acordar de qué VM guarda qué datos, qué contenedor depende de qué base de datos, dónde están los backups, qué volumen era importante y qué regla de firewall pusiste aquella noche. Luego pasan tres meses, algo falla y te encuentras leyendo nombres de contenedores como si fueran inscripciones de una civilización perdida.
No creo que un homelab doméstico necesite documentación de consultora. De hecho, si la documentación da más trabajo que el sistema, está mal planteada. Pero sí necesita un inventario mínimo. No para presumir. Para reparar, migrar, apagar y dormir más tranquilo.
La documentación útil responde preguntas feas#
Una documentación bonita no sirve de mucho si no responde las preguntas que aparecen cuando algo se rompe.
Las preguntas que me importan son bastante concretas:
- Qué servicios tengo corriendo.
- Dónde corre cada servicio.
- Qué datos guarda.
- De qué depende para arrancar.
- Cómo se actualiza sin jugar a la ruleta.
- Dónde está su backup.
- Cómo se restaura.
- Qué impacto tiene si lo apago.
- Quién lo usa.
Si un inventario no responde eso, probablemente es decoración. Puede tener iconos, diagramas, colores y una portada preciosa, pero en una incidencia lo que quiero es saber si puedo apagar una VM sin llevarme por delante las fotos familiares.
La documentación doméstica tiene que ser fea si hace falta, pero útil.
Mi unidad mínima: una ficha por servicio#
A mí me funciona pensar en fichas de servicio. Una por cada cosa que vive en el homelab y que quiero recordar.
No hace falta complicarlo. Una ficha puede ser un archivo Markdown, una página en una wiki, una nota en Obsidian, un documento en Paperless, un repositorio Git o incluso una hoja de cálculo si eso hace que lo mantengas.
La estructura que más uso es esta:
- Nombre del servicio.
- Para qué sirve.
- Dónde corre.
- Tipo de despliegue.
- Datos importantes.
- Dependencias.
- Backup.
- Restauración.
- Actualización.
- Impacto si cae.
- Notas raras.
Lo importante no es el formato. Es que exista y que puedas encontrarlo.
Un ejemplo simplificado para un servicio de fotos sería algo así:
| |
Esto no gana premios de documentación. Pero si un día tengo que moverlo, ya no empiezo de cero.
Inventario de máquinas: menos datos, más intención#
El inventario de VMs, LXCs y servidores físicos suele degenerar rápido. Se empieza apuntando lo básico y se acaba con una tabla enorme que nadie actualiza.
Yo prefiero pocos campos, pero bien elegidos:
- Nombre genérico.
- Rol.
- Host o cluster donde vive.
- Recursos aproximados.
- Sistema operativo.
- Criticidad.
- Backup sí o no.
- Servicios que contiene.
- Notas de mantenimiento.
No necesito apuntar cada paquete instalado. Para eso ya está el sistema. Tampoco necesito documentar cada puerto si el reverse proxy y el firewall ya tienen su propia configuración. Lo que quiero es entender el mapa.
La criticidad ayuda mucho. Uso algo parecido a esto:
- Crítico: si cae, afecta a la casa o a datos importantes.
- Importante: lo uso a menudo, pero puede esperar unas horas.
- Cómodo: molesta si cae, pero no pasa nada serio.
- Laboratorio: puede romperse sin drama.
- Candidato a apagar: no está claro por qué sigue vivo.
Esa última categoría es oro. Si algo lleva dos revisiones como candidato a apagar, probablemente hay que apagarlo. El homelab no necesita cementerios encendidos.
Dependencias: el mapa que nadie quiere hacer#
Las dependencias son la parte que más se ignora y la que más duele cuando falla.
Un servicio rara vez vive solo. Puede depender de DNS, una base de datos, un volumen NFS, un proxy, certificados, autenticación, una cola, almacenamiento externo, otro contenedor o una ruta de red concreta. Cuando todo funciona, esas dependencias son invisibles. Cuando algo cae, aparecen de golpe.
No hace falta dibujar un mapa perfecto. Basta con apuntar las dependencias que cambiarían una restauración.
Por ejemplo:
- Si el servicio necesita PostgreSQL, quiero saber si la base va dentro del mismo stack o en otra máquina.
- Si usa almacenamiento de red, quiero saber qué pasa si el NAS no arranca.
- Si depende de SSO, quiero saber si existe acceso local de emergencia.
- Si usa proxy interno, quiero saber si puedo acceder por IP y puerto en caso de apuro.
- Si necesita DNS interno, quiero saber qué nombre resuelve y dónde se define.
Esto parece obvio hasta que una migración rompe algo y descubres que el servicio no fallaba por el contenedor, sino porque dependía de una ruta montada que nadie recordaba.
Backups: documentar la restauración, no solo la copia#
Apuntar “tiene backup” es casi inútil. La pregunta buena es otra: cómo vuelve.
En la ficha de cada servicio intento separar tres cosas.
Primero, qué se copia. Código de despliegue, variables de entorno saneadas, base de datos, archivos subidos, volúmenes, configuraciones, certificados si aplica. Muchos servicios tienen la parte importante repartida. Si solo copias el directorio de Docker y te olvidas de la base de datos externa, tienes media promesa.
Segundo, dónde se copia. NAS, disco externo, otro servidor, nube, Proxmox Backup Server, Restic, Borg, Kopia, lo que sea. No hace falta que todos los servicios tengan el mismo sistema, pero sí que se entienda.
Tercero, cómo se restaura. Este es el punto que casi nadie escribe. Y es el que salva tiempo.
Un procedimiento mínimo puede ser:
| |
No hace falta que sea perfecto. Hace falta que exista antes del día malo.
Nombres: aburridos mejor que ingeniosos#
A todos nos gusta poner nombres con gracia. Yo también he caído. Pero para inventario y operación, los nombres ingeniosos envejecen regular.
Un hostname puede tener personalidad, pero el rol tiene que estar claro. Si una máquina se llama “batcueva” y dentro vive DNS, backups, Home Assistant y media server, el nombre no ayuda demasiado. Prefiero que el inventario diga claramente “servicios-domesticos”, “storage”, “lab-k8s”, “monitoring” o “backup”.
No digo que haya que renunciar al humor. Digo que cuando algo se rompe a las doce de la noche, un nombre descriptivo vale más que una referencia brillante.
También conviene evitar que el nombre del servicio y el nombre de la máquina se confundan. Una VM puede contener varios servicios. Un servicio puede migrar de máquina. Si el inventario está atado al hardware, cada migración se vuelve más confusa.
Diagramas pequeños, no murales imposibles#
Los diagramas ayudan, pero tienen un problema: si son demasiado ambiciosos se quedan obsoletos en dos semanas.
Me gustan más los diagramas pequeños por capas:
- Red básica: router, VLANs principales, DNS, acceso remoto.
- Datos: NAS, backups, almacenamiento externo.
- Servicios críticos: dónde viven y de qué dependen.
- Laboratorio: límites y acceso.
Cuatro diagramas simples suelen ser más útiles que un mural enorme con todas las flechas del universo.
Además, un diagrama no tiene que ser bonito. Puede ser Mermaid, Excalidraw, Draw.io, una captura anotada o texto. Lo importante es que se pueda corregir rápido. Si actualizar el diagrama da pereza, dejará de representar la realidad.
Automatizar el inventario sin volverse loco#
Hay una parte del inventario que se puede automatizar. Listar VMs, contenedores, servicios Docker, direcciones internas, snapshots o tamaños de volúmenes. Eso está bien, pero no sustituye la documentación humana.
Un script puede decirme que existe una VM con 4 GB de RAM y dos discos. No puede decirme por qué existe, quién la usa, si puedo apagarla o qué datos son irreemplazables.
La mejor combinación es mezclar inventario automático con notas manuales.
- Automático para estado actual.
- Manual para intención, impacto y recuperación.
Si tengo que elegir, prefiero una nota manual desactualizada una semana que un CSV perfecto sin contexto. La máquina sabe contar recursos. Yo tengo que explicar por qué importan.
Revisión mensual: el inventario como detector de basura#
El inventario no solo sirve para reparar. Sirve para limpiar.
Una vez al mes, o cuando me acuerdo con algo de culpa, reviso tres cosas:
- Servicios sin backup claro.
- Máquinas sin propietario mental.
- Dependencias raras que no recordaba.
Los servicios sin backup claro se arreglan o se degradan a laboratorio. Si algo no merece backup, quizá no merece producción.
Las máquinas sin propietario mental son esas que nadie sabe explicar. “Creo que ahí estaba probando algo” no es un rol. Si no puedo decir para qué sirve, la apago primero y la borro después de un margen razonable.
Las dependencias raras son las más peligrosas. Un servicio crítico que depende de un NAS montado a mano, una base de datos en otra VM olvidada o una regla de firewall puesta hace meses. No siempre hay que cambiarlas al momento, pero sí sacarlas a la luz.
Un buen inventario incomoda un poco. Te enseña deuda técnica que antes estaba escondida.
Qué no documento#
También merece la pena decidir qué no se documenta.
No documento cada comando rutinario. No documento cada actualización menor. No documento configuraciones que ya viven en Git salvo que tengan una decisión detrás. No documento puertos internos si están claros en el compose. No documento cosas temporales que van a morir en una semana.
La documentación excesiva tiene un coste. Si todo requiere actualizar tres sitios, acabaré no actualizando ninguno. Prefiero documentar menos y mantenerlo vivo.
Mi regla es esta: documento lo que necesitaría saber para apagar, mover, restaurar o delegar un servicio.
Si no entra en una de esas acciones, probablemente sobra.
El formato que de verdad se mantiene#
El mejor sistema de documentación no es el más completo. Es el que abres de verdad.
Para mí, lo ideal es algo versionado, buscable y rápido. Markdown en Git funciona muy bien. Una wiki ligera también. Obsidian encaja si ya lo usas. Incluso una carpeta de notas con nombres claros puede ser suficiente.
Lo que evitaría es montar una plataforma enorme solo para documentar una infraestructura pequeña. Si necesitas mantener la herramienta de documentación como si fuera otro servicio crítico, quizá te has complicado demasiado.
El inventario tiene que sobrevivir aunque el homelab esté caído. Esto parece una tontería, pero no lo es. Si tu documentación vive solo dentro del servidor que intentas recuperar, has creado una broma bastante cruel.
Una copia local, una copia en Git remoto o una exportación sencilla pueden marcar la diferencia.
Mi conclusión práctica#
Documentar un homelab no va de hacerlo perfecto. Va de quitar incertidumbre cuando menos apetece pensar.
Quiero saber qué tengo, dónde vive, qué datos guarda, cómo se copia y cómo vuelve. Quiero distinguir servicios reales de juguetes. Quiero poder apagar cosas sin miedo. Quiero que una migración no dependa de mi memoria de hace seis meses.
Y sobre todo quiero evitar el clásico momento de mirar una VM y pensar: “¿esto era importante?”
Si el inventario evita esa pregunta una sola vez, ya ha merecido la pena.