GitOps en casa suena muy serio. Demasiado serio, incluso. La palabra trae olor a Kubernetes, pipelines, pull requests, entornos, ramas, revisiones y ese tipo de cosas que en una empresa pueden tener sentido y en un homelab pequeño pueden convertirte en el empleado más cansado de tu propia casa.
Aun así, la idea de fondo me parece buenísima: que la configuración importante viva en Git, que los cambios queden registrados y que puedas reconstruir servicios sin depender de una tarde de memoria heroica.
El problema es la dosis.
Si no versionas nada, tu homelab acaba siendo una mezcla de carpetas, cambios manuales, contenedores que funcionan por motivos históricos y notas sueltas. Si versionas absolutamente todo y montas una plataforma de despliegue como si fueras una fintech con guardias 24/7, acabas manteniendo más proceso que servicios.
El punto interesante está en medio. GitOps doméstico, pero sin fliparse.
qué entiendo por GitOps en casa#
No hablo de montar Argo CD, Flux, entornos declarativos completos y revisión formal para cambiar el puerto de un contenedor. Eso puede tener sentido si ya usas Kubernetes en serio o si el objetivo principal es aprender esas herramientas. Para un homelab pequeño, muchas veces basta con algo más sencillo.
Para mí, GitOps doméstico significa tres cosas.
La configuración importante está en un repositorio.
Los cambios pasan por archivos, no por memoria y clics sueltos.
Restaurar un servicio no depende de adivinar cómo estaba montado.
Eso ya es bastante. No hace falta convertir cada docker compose en una epopeya. Git no arregla una mala arquitectura, pero sí deja rastro. Y en un homelab, el rastro vale oro cuando vuelves a un servicio seis meses después y no recuerdas por qué tenía esa variable rara.
el caos que intenta resolver#
El caos típico de un homelab no aparece el primer mes. Aparece cuando llevas tiempo.
Un contenedor se montó rápido para probar. Luego se quedó. Una variable de entorno se cambió directamente en el servidor. Un volumen apunta a una ruta que parecía temporal. Un reverse proxy tiene una regla creada desde la interfaz. Un cron está en una máquina que no recordabas. Una contraseña está en un .env que no sabes si está respaldado. Un servicio funciona, pero nadie se atreve a tocarlo.
Ese es el momento en que Git empieza a tener sentido.
No porque sea elegante. Porque reduce miedo.
Cuando la configuración vive en un repositorio, puedes mirar historia. Puedes comparar antes y después. Puedes volver a una versión anterior. Puedes reconstruir una VM nueva sin jugar a arqueología. Puedes revisar qué servicios dependen de qué carpetas, dominios y variables.
Y, sobre todo, dejas de confiar tanto en tu yo del pasado. Mi yo del pasado es muy optimista documentando mentalmente cosas. No le contrataría para operaciones.
lo que sí versionaría#
Empezaría por lo que más ayuda a reconstruir.
Versionaría archivos docker-compose.yml o equivalentes. Son el mapa más útil de muchos servicios domésticos: imágenes, puertos, volúmenes, redes, healthchecks y dependencias. Si mañana pierdo una máquina, quiero poder leer cómo levantaba Vaultwarden, Uptime Kuma, Paperless-ngx, Immich o el reverse proxy.
Versionaría plantillas de configuración. Nginx, Traefik, Caddy, AdGuard, Pi-hole, servicios de backup, alertas y scripts pequeños de mantenimiento. No necesariamente cada archivo generado por una app, pero sí lo que he escrito yo y necesito entender.
Versionaría documentación operativa corta. Un README.md por servicio con qué es, dónde vive, qué datos necesita, dónde están los backups y cómo se restaura. No una novela. Una ficha útil para una tarde con sueño.
Versionaría scripts propios. Backups, comprobaciones, tareas de mantenimiento, exports, avisos. Si el script afecta a datos o disponibilidad, debe tener historia.
Versionaría inventario. Lista de servicios, puertos, dominios internos, rutas de datos, dependencias y prioridad de recuperación. Esto no tiene que ser perfecto. Tiene que existir.
Versionaría configuraciones de infraestructura cuando sean estables. Ansible, Terraform, cloud-init, plantillas de VM, manifiestos de Kubernetes si los usas de verdad. Si una pieza se usa para construir otras, tiene que estar en Git.
Todo esto tiene una cosa en común: si desaparece, reconstruir duele.
lo que no metería en Git#
No metería secretos en Git. Parece obvio, pero es la metedura de pata más fácil. Tokens, contraseñas, claves privadas, cookies, certificados privados, variables sensibles y dumps de base de datos no pertenecen a un repositorio normal.
Tampoco metería datos vivos de aplicaciones. Fotos, documentos, bases de datos, adjuntos, bibliotecas y volúmenes enteros van a backups, no a Git.
No versionaría archivos generados que cambian todo el rato y no aportan comprensión. Logs, cachés, estados internos, bases SQLite activas, directorios de runtime. Meter eso en Git solo añade ruido.
No metería configuraciones que no entiendo solo porque están en una carpeta. Si una app genera cincuenta archivos y no sé cuáles son relevantes, prefiero documentar cómo exportarla o respaldar su volumen con una estrategia de backup, no fingir que Git es una papelera con historia.
Y no versionaría todo el sistema operativo. Para un homelab pequeño, copiar /etc entero a Git suele ser una mala señal. Hay archivos que sí importan, claro. Pero si el plan es “meto todo por si acaso”, probablemente necesito ordenar antes.
la regla de oro: repositorio limpio, backups aparte#
Git no es backup de datos. Git no es gestor de secretos. Git no es copia completa de un servidor.
Git es memoria de configuración.
Esa frase me ayuda a no mezclar capas. Los datos importantes van a backups con retención y restauración probada. Los secretos van a un gestor de contraseñas o a un sistema pensado para secretos. Las configuraciones van a Git. Las notas operativas van a Git o a una wiki versionada.
Cuando mezclas todo, acabas con repositorios peligrosos, backups incompletos y una falsa sensación de control.
Me gusta que el repositorio pueda ser privado, pero aun así lo trato como si algún día pudiera filtrarse. Eso cambia cómo escribes. No pones IPs reales si no hacen falta. No pones dominios internos sensibles. No pones tokens. No pones comentarios tipo “esta clave es la buena”. Parece de cajón, pero los repositorios personales tienen una capacidad tremenda para convertirse en cajones con dinamita.
mi estructura simple#
Para un homelab pequeño usaría una estructura aburrida.
| |
Nada revolucionario. Justo por eso funciona.
Cada servicio tiene lo mínimo para entenderlo. El compose.yml describe cómo levanta. El env.example muestra qué variables necesita sin revelar valores reales. El README.md explica dónde están los datos, cómo se actualiza y cómo se restaura.
La carpeta infra guarda piezas compartidas. DNS, proxy, backups y monitorización. La carpeta scripts guarda automatizaciones pequeñas. La carpeta docs guarda lo que desbloquea una recuperación.
La estructura ideal no es la que gana un concurso de arquitectura. Es la que sigues usando tres meses después.
cómo gestionaría secretos#
En casa, la solución más simple suele ganar.
Para variables sensibles, usaría archivos .env reales fuera de Git y dejaría solo .env.example. El ejemplo debe tener nombres de variables, valores falsos y alguna pista de formato si hace falta.
Para contraseñas y tokens, un gestor tipo Vaultwarden, 1Password, Bitwarden o el que uses de verdad. Lo importante es que también tenga backup y acceso de emergencia. Si tus secretos están en un gestor self-hosted que depende del mismo homelab caído, necesitas un plan B.
Si el entorno crece, puedes mirar SOPS, age, Ansible Vault o secretos cifrados en Git. Pero no empezaría por ahí en un homelab pequeño salvo que tengas claro el flujo. Cifrar secretos en Git suena bien hasta que pierdes la clave, mezclas destinatarios o nadie recuerda cómo desplegar.
Mi regla práctica: si una solución de secretos me impide restaurar cuando estoy cansado, no es una solución. Es una trampa con documentación.
automatizar despliegues, pero con freno#
Aquí es donde GitOps se puede ir de las manos.
Hay una versión sencilla: haces cambios en Git, entras al servidor y aplicas. Manual, claro, pero con historia. Para muchos homelabs, esto ya es una mejora enorme.
Luego puedes añadir automatización ligera. Un script que hace pull, valida compose y recrea servicios concretos. Una tarea que avisa de cambios pendientes. Renovate proponiendo actualizaciones de imágenes. Dockge o Portainer leyendo stacks desde Git. Algo así.
Lo que no haría al principio es autoaplicar cualquier cambio en cuanto se haga push. En producción doméstica eso puede ser cómodo, pero también puede romper la cena por un typo.
Prefiero que los servicios familiares tengan despliegue deliberado. Pull, revisión rápida, backup si toca, aplicar. Los servicios de laboratorio sí pueden ir más automáticos. Ahí está bien aprender y romper.
No todo merece la misma política. Un dashboard personal puede actualizarse solo. Immich, Paperless, Vaultwarden, DNS o Home Assistant merecen más respeto.
cambios pequeños con commits útiles#
Una ventaja inesperada de Git es que te obliga a nombrar cambios. Eso ayuda.
No hace falta escribir literatura en los commits. Pero sí algo más útil que “update”. Ejemplos buenos:
| |
Cuando algo falla, esos mensajes cuentan una historia. Ves qué tocaste, cuándo lo tocaste y por qué zona mirar.
También evitaría agrupar cambios sin relación. Si actualizo un servicio, cambio el proxy y retoco backups en el mismo commit, mi yo futuro tendrá que separar el nudo. Mejor commits pequeños y con sentido.
Esto no es burocracia. Es dejar migas de pan para el día que algo huela raro.
revisión antes de tocar producción#
No necesito una pull request formal para cambiar mi homelab, pero sí una pausa mínima.
Antes de aplicar un cambio importante, miro cuatro cosas.
- Qué servicio toca.
- Qué datos podrían verse afectados.
- Si existe backup reciente.
- Cómo vuelvo atrás.
Si no sé contestar eso, el cambio espera.
Esto vale especialmente para actualizaciones de imágenes. El botón de actualizar todo es tentador. También es una forma rápida de convertir cinco servicios sanos en cinco incógnitas. Prefiero actualizar por grupos: primero laboratorio, luego servicios de baja prioridad, luego servicios críticos con más cuidado.
Git ayuda porque puedo ver el diff. Si una imagen cambia de versión, si un volumen se mueve, si una variable desaparece, si un puerto cambia, lo veo antes de aplicar. La interfaz web de algunas herramientas es cómoda, pero el diff de Git sigue siendo brutalmente honesto.
documentación que sí escribiría#
La documentación de un homelab no debería parecer una auditoría ISO. Si da pereza abrirla, no sirve.
Por servicio escribiría esto:
- Qué hace.
- Por qué existe.
- Dónde corre.
- Dónde están sus datos.
- Qué depende de él.
- Cómo se hace backup.
- Cómo se restaura.
- Qué no tocar sin mirar antes.
Con diez líneas suele bastar. Si un servicio necesita tres páginas para explicar cómo revivirlo, igual el problema no es la documentación.
También tendría una página de recuperación general. Orden de restauración, credenciales de emergencia, servicios críticos, DNS básico, backups y enlaces internos. Esa página puede salvar más tiempo que cualquier dashboard bonito.
Y aquí Git encaja muy bien. La documentación vive al lado de la configuración. Cuando cambias una ruta, actualizas el README. Si no lo haces, el diff te delata.
el límite: no todo debe ser declarativo#
Hay una fantasía muy común: si todo está declarativo, todo se puede reconstruir perfecto. En empresa ya es difícil. En casa, más.
Hay cosas que no merece la pena declarar con precisión quirúrgica. Ajustes pequeños de una app, preferencias de usuario, integraciones que cambian poco, pruebas temporales, dashboards personales. Puedes documentarlas si son importantes, pero no necesitas convertir cada click en código.
También hay servicios que tienen su propio sistema de exportación. Home Assistant, por ejemplo, tiene backups completos que pueden ser más prácticos que intentar reconstruir cada integración desde Git. Paperless tiene datos y metadatos que requieren backup real. Immich necesita base de datos y originales. Git no sustituye eso.
El objetivo no es vivir en una maqueta perfecta. El objetivo es reducir incertidumbre.
Si GitOps añade claridad, adelante. Si añade miedo a tocar cualquier cosa porque el proceso es demasiado pesado, te has pasado.
cómo empezaría esta semana#
Si hoy tuviera un homelab con cosas funcionando y poco versionado, no intentaría arreglarlo todo de golpe.
Empezaría por un repositorio privado. Luego elegiría tres servicios importantes, no treinta. Por ejemplo: reverse proxy, backups y un servicio crítico como Vaultwarden o Paperless.
Copiaría sus compose, ejemplos de variables y README mínimo. Revisaría que no hay secretos. Haría un commit por servicio. Después documentaría rutas de datos y procedimiento de restauración.
La semana siguiente añadiría otros dos o tres. Luego scripts. Luego inventario. Luego automatización si todavía tiene sentido.
La clave es que el repositorio empiece a pagar alquiler desde el primer día. Si en una semana ya te ayuda a entender mejor tres servicios, va bien. Si solo tienes una estructura preciosa vacía, es decoración técnica.
errores que evitaría#
El primero: meter secretos. No hay mucho más que decir. No lo hagas.
El segundo: versionar configuraciones copiadas sin probar que sirven. Un compose viejo en Git da falsa seguridad. Hay que levantar o validar de vez en cuando.
El tercero: automatizar despliegues críticos demasiado pronto. Primero control, luego automatización.
El cuarto: no documentar datos. Saber levantar el contenedor no basta si no sabes dónde vive la información importante.
El quinto: convertir Git en sustituto de backups. Git guarda texto. Tus fotos, documentos, bases de datos y volúmenes necesitan otra estrategia.
El sexto: hacerlo tan perfecto que no lo mantienes. La mejor estructura es la que sobrevives usando.
cuándo sí me plantearía GitOps más serio#
Si el homelab crece, la cosa cambia.
Con Kubernetes real, varios nodos, muchos servicios y necesidad de recrear entornos, herramientas como Flux o Argo CD empiezan a tener sentido. Con Ansible, Terraform o cloud-init también puedes llevar más infraestructura a código. Si tienes servicios públicos, varios servidores o dependencias delicadas, el proceso aporta seguridad.
Pero lo metería por necesidad, no por estética.
Para una casa con un servidor Docker y diez servicios, un repositorio bien cuidado puede ser suficiente. Para un cluster K3s con almacenamiento distribuido y despliegues frecuentes, GitOps completo puede ser una buena inversión.
La diferencia está en el coste de equivocarte y en la frecuencia de cambio.
mi conclusión#
GitOps doméstico merece la pena cuando te ayuda a recordar, reconstruir y tocar menos a ciegas. No merece la pena cuando convierte un homelab pequeño en una empresa imaginaria con demasiadas normas.
Yo versionaría compose, configuraciones escritas a mano, scripts, inventario y documentación operativa. Dejaría fuera secretos, datos vivos, logs y ruido generado. Automatizaría con cuidado, especialmente en servicios familiares. Y mantendría backups como una capa separada, porque Git no va a rescatar una base de datos rota ni una carpeta de fotos perdida.
La idea buena no es “todo en Git”. La idea buena es “lo necesario en Git para no depender de memoria y suerte”.
Eso, en un homelab, ya es bastante victoria.