Dockhand v1.0.45 integra KeePassXC en los despliegues Compose
Dockhand puede resolver secretos desde KeePassXC al desplegar stacks y detectar fallos habituales antes de aplicar Compose.
El problema no es usar variables, sino dónde acaba la contraseña
En muchos homelabs, el fichero compose.yaml vive en Git y las variables sensibles terminan en un .env apartado. Es una mejora respecto a escribir contraseñas directamente en el Compose, pero sigue dejando un fichero que hay que proteger, copiar y sincronizar entre máquinas. También es habitual que ese .env acabe en una copia de seguridad, en un directorio compartido o, por error, dentro del repositorio.
Dockhand v1.0.45 añade KeePassXC como proveedor de secretos para resolver ese caso. La idea es mantener las credenciales en una base de datos local .kdbx y pedirlas únicamente cuando se despliega el stack. El valor resuelto se pasa a Docker Compose durante la operación, pero Dockhand no lo escribe en el .env persistente ni en el fichero Compose.
Referencias keepass:// dentro del stack
El proveedor usa keepassxc-cli, que debe instalar o proporcionar quien opera Dockhand. La aplicación no incluye el binario ni descarga KeePassXC por su cuenta, así que hay que montar la base de datos y, si hace falta, el cliente dentro del contenedor. Por defecto busca el ejecutable en /usr/bin/keepassxc-cli, aunque se puede indicar otra ruta absoluta con DOCKHAND_KEEPASSXC_CLI_PATH.
Una referencia individual sigue el formato keepass://GROUP/ENTRY/FIELD. Los grupos pueden estar anidados, el último segmento identifica el atributo y los anteriores forman la ruta de la entrada. Además de Password, se pueden leer UserName, URL y atributos personalizados de la entrada de KeePassXC.
services:
dockhand:
image: fnsys/dockhand
volumes:
- dockhand_data:/app/data
- /host/secrets/passwords.kdbx:/secrets/passwords.kdbx:ro
- /host/secrets/db.keyx:/secrets/db.keyx:ro
- /opt/dockhand-tools/keepassxc-cli:/usr/bin/keepassxc-cli:ro
volumes:
dockhand_data:Una vez configurado el proveedor en Settings → Secrets, se define la ruta de la base de datos vista desde el contenedor y se indica una contraseña maestra, un fichero de clave o ambos. La contraseña maestra se entrega a keepassxc-cli por la entrada estándar, no como argumento de la línea de comandos. Después, en las variables del stack se puede usar algo como DB_PASSWORD=keepass://Web/Postgres/Password y referenciarlo desde Compose mediante ${DB_PASSWORD}.
También puede cargar grupos completos
No todo tiene que resolverse secreto a secreto. Dockhand permite usar un grupo de KeePassXC como selector mediante DOCKHAND_SECRET_SELECTOR. Cada entrada de ese grupo se convierte en una variable con el título de la entrada como nombre y con su campo Password como valor.
Este modo obliga a cuidar los nombres de las entradas. Un título con espacios o guiones no es un nombre válido de variable de entorno y Dockhand lo omite con una advertencia. Si el mismo título existe en varios subgrupos, gana la primera coincidencia, así que conviene evitar duplicados ambiguos.
Validar antes de darle a desplegar
La otra parte útil de esta versión está en Compose validate. Dockhand combina la validación de docker compose config con sus propias reglas, de modo que puede avisar tanto de errores de sintaxis o esquema como de configuraciones válidas pero poco recomendables. La validación se ejecuta antes del despliegue y muestra los problemas en el editor y en un panel de resultados.
Entre las sugerencias aparecen los servicios sin healthcheck y los volúmenes con nombre declarados en la raíz del fichero que no monta ningún servicio. No son errores que impidan ejecutar Compose, y no deberían tratarse como tales. Pero sí son dos señales útiles para revisar un stack antes de añadirlo al homelab o automatizar sus actualizaciones.
Un aviso no sustituye una decisión técnica
Un healthcheck vacío, lento o que consulta algo irrelevante no mejora la disponibilidad por el mero hecho de existir. Hay servicios donde no tiene sentido definirlo, y otros donde la imagen ya aporta uno adecuado. La advertencia sirve para hacer la pregunta correcta: qué condición debe cumplir el contenedor para considerarse realmente listo.
Lo mismo ocurre con los volúmenes sin uso. A veces son restos de una configuración anterior y se pueden eliminar; otras veces pueden estar reservados para un perfil, un override o un cambio pendiente. Antes de borrar nada, revisaría el Compose efectivo, los ficheros adicionales y los perfiles que utilice el despliegue.
La letra pequeña de KeePassXC
Esto no convierte a KeePassXC en un servicio centralizado de secretos ni elimina la necesidad de proteger el host. Dockhand necesita acceso de lectura a la base .kdbx y, según la configuración, al fichero de clave; quien controle el servidor y la configuración del proveedor tendrá una posición sensible. Tampoco hay una red de por medio: es una integración local basada en la base de datos y en keepassxc-cli.
Hay otro detalle importante: la imagen oficial de Dockhand es minimalista y no incorpora un gestor de paquetes ni KeePassXC. Montar únicamente el binario puede no bastar, porque el cliente arrastra dependencias compartidas. En sistemas con SELinux, los montajes también necesitan el etiquetado adecuado, como :z o :Z, para que el proceso pueda leer los archivos.
Para un homelab que ya usa KeePassXC como fuente de verdad, esta integración evita duplicar contraseñas en ficheros de despliegue. La validación de Compose complementa bien esa mejora porque ayuda a detectar descuidos que normalmente salen a la luz después. Ninguna de las dos funciones sustituye revisar el stack, pero ambas reducen trabajo manual y puntos de fuga innecesarios.