Dejá de traducir a mano docker-compose a Quadlet

En pocas palabras: QuadletGen es una herramienta web gratuita que automatiza la conversión de docker-compose.yml a archivos .container, .volume y .network de Podman Quadlet. Ofrece un informe de cobertura que clasifica cada clave en Converted, Warning o Skipped, permitiendo identificar qué ajustes manuales son necesarios.

Si alguna vez tuviste que migrar un stack de Docker Compose a Podman Quadlet, sabés que la parte más embolante no es entender systemd — es traducir cada puerto, volumen, healthcheck y depends_on línea por línea, con el riesgo de que un typo te rompa algo en producción sin avisar. Un desarrollador publicó QuadletGen, una herramienta que funciona en el navegador y automatiza esa traducción, con un informe de cobertura que te dice exactamente qué se convirtió, qué necesita revisión y qué no se puede automatizar.

QuadletGen es una herramienta de conversión: tomás un archivo docker-compose.yml, lo pegás en el navegador y te devuelve los archivos Quadlet listos para usar en Podman con systemd, clasificando cada clave como Converted, Warning o Skipped, y adaptando la configuración para ejecución rootless o rootful.

¿Por qué es tedioso traducir manualmente docker-compose a Quadlet?

El formato es el primer escollo. Docker Compose usa YAML con sangrías, listas y objetos anidados; Quadlet trabaja con archivos .container, .volume y .network en sintaxis INI plana — cada directiva es una clave=valor dentro de una sección [Unit], [Container] o [Network]. Cuando tenés un stack de tres servicios con healthchecks, varias redes y volúmenes nombrados, la conversión a mano te obliga a rastrear cada referencia y reescribirla sin equivocarte.

Por ejemplo, si tenés un servicio con depends_on y un healthcheck condicional, en Compose es una línea dentro del servicio; en Quadlet, dependencias entre unidades se manejan con Requires=, After= y Upholds= de systemd, y los healthchecks se definen por separado en la directiva HealthCmd. Un error en el nombre de una unidad o un healthcheck que queda con valores por defecto distintos puede hacer que un contenedor inicie antes de que su dependencia esté lista (y a veces ni te enterás hasta que algo falla en producción).

¿El resultado? Migrar una app de prueba te lleva diez minutos; migrar un stack real con diez servicios y varios volúmenes, una tarde entera. Y la fatiga manual abre la puerta a errores silenciosos que después rastreás a las 3 AM. Relacionado: nuestra comparativa de CI/CD 2026.

¿Qué es QuadletGen y cómo automatiza la conversión?

QuadletGen es una aplicación web que tomó el problema y lo resolvió en el navegador. Pegás tu archivo Compose, elegís entre modo rootless o rootful, y la herramienta genera los archivos .container, .volume y .network al instante, según el anuncio original en devencyclopedia.com de mayo 2026. Nada de instalar CLIs ni dependencias extra: funciona directo en el browser.

La magia está en el mapeo automático que cubre:

• image → Image=
• ports → PublishPort= (con ajustes según rootless)
• environment → Environment=
• volumes → separa volúmenes nombrados en archivos .volume con Volume= y monta el path en el .container
• networks → genera archivos .network y asigna Network=
• depends_on → mapea a Requires=/After= en systemd
• restart → Restart=
• command → Exec= (si sobrescribe el entrypoint)
• healthcheck → HealthCmd= y parámetros asociados

Además, los volúmenes y redes que usan varios servicios los detecta y los separa en unidades independientes, como manda la filosofía Quadlet. Eso te ahorra el trabajo de identificar dependencias compartidas y crear los archivos a mano.

¿Cómo interpretar el informe de cobertura de QuadletGen?

Lo que de verdad hace útil esta herramienta para un entorno de producción es que no te larga los archivos y te desea suerte. Cada clave de tu docker-compose.yml aparece clasificada en tres categorías, justo después de la conversión:

• Converted: la clave se tradujo sin cambios a la directiva Quadlet equivalente. Por ejemplo, un ports: "8080:80" queda como PublishPort=8080:80.
• Warning: se convirtió, pero el comportamiento no es idéntico al de Docker Compose. El caso típico que menciona la fuente es depends_on con condition: service_healthy — Quadlet puede representar la dependencia, pero la semántica de systemd para asegurar que un servicio esté healthy antes de arrancar otro no es exactamente la misma que en Docker.
• Skipped: claves que no se pueden traducir automáticamente, como build (porque Quadlet no construye imágenes, usa imágenes preexistentes) o secrets (que en Docker se manejan con el backend de secrets y en Quadlet tenés que resolver con systemd-creds u otro mecanismo).

El informe te da visibilidad inmediata sobre qué partes de tu stack requieren revisión post-conversión. No es un botón mágico, pero sabés dónde poner el ojo.

¿Qué diferencias hay entre el modo rootless y rootful en QuadletGen?

QuadletGen te pregunta al inicio si querés la salida para Podman rootless (el usuario sin privilegios) o rootful. La diferencia principal está en los puertos y los paths de los volúmenes. En modo rootless, los puertos por debajo del 1024 requieren configuración adicional de systemd, y los volúmenes suelen residir en ~/.local/share/containers/storage/volumes; la herramienta ajusta automáticamente las rutas y los mapeos de PublishPort para que la unidad funcione sin root.

Si estás corriendo servicios en un homelab o en un VPS con CentOS Stream o RHEL, el modo rootless es la opción más segura, y QuadletGen te ahorra tener que revisar docenas de líneas para cambiar permisos. En analizamos Jenkins vs GitHub Actions profundizamos sobre esto.

¿Qué hacer con las claves omitidas como build y secrets?

Las claves Skipped aparecen porque no tienen un equivalente directo en el modelo de Quadlet. build asume que tenés un Dockerfile y que el orquestador construye la imagen antes de correr el contenedor; en Quadlet la imagen tenés que tenerla ya compilada y disponible en tu registro local o remoto. La herramienta te recomienda el paso manual de hacer podman build por separado y apuntar el .container a la imagen resultante.

Para secrets, QuadletGen sugiere que uses systemd-creds o montes archivos de secretos como volúmenes bind con permisos restringidos. No es un reemplazo uno a uno, pero el informe te deja claro que esas líneas no se van a traducir y te da el contexto para resolverlo.

¿Cómo manejar depends_on y healthchecks en Quadlet con ayudas de la herramienta?

El traductor convierte depends_on a Requires= y After= dentro del archivo .container. Si la condición es service_healthy, la directiva se convierte pero QuadletGen la marca como Warning, avisándote que systemd no tiene un equivalente nativo al healthcheck de Docker para condicionar el inicio de otra unidad. Lo que podés hacer es apoyarte en ExecCondition= o en un script que verifique el estado del servicio antes de arrancar, pero eso ya corre por tu cuenta.

Los healthchecks en sí se traducen a HealthCmd=, HealthInterval= y demás, y eso funciona parecido. El punto crítico es la dependencia condicional: QuadletGen te la convierte para que no se pierda, pero te alerta de que el comportamiento final puede diferir y que tenés que testearlo en tu entorno.

Ejemplo práctico: convertir un stack con WordPress y MySQL

Este es un caso típico que cualquiera que haya hosteado un WordPress conoce. Un docker-compose.yml sencillo con un servicio de WordPress, MySQL, un volumen para la base de datos y una red propia. El archivo original sería algo así (resumido): Ya lo cubrimos antes en la guía de hreflang para SEO.

• Servicio db: imagen mysql:8, volumen db_data, red wp-net, healthcheck, restart always.
• Servicio wordpress: imagen wordpress:latest, puerto 8080:80, variables de entorno, depends_on db con condition service_healthy, misma red.
• Volumen db_data y red wp-net declarados al final.

QuadletGen produce tres archivos: wordpress.container, db.container y db_data.volume, más wp-net.network. En wordpress.container verías Requires=db.service y After=db.service con un cartelito de Warning porque el depends_on era condicional. Los healthchecks quedan en cada .container con su comando. Las variables de entorno aparecen línea por línea en Environment=. El puerto mapeado se convierte en PublishPort=8080:80. El volumen db_data se convierte en un archivo de volumen independiente que luego se referencia en el .container de db. La red se genera en wp-net.network.

Si corrés esto en un entorno rootless, los permisos de PublishPort se adaptan para usar un puerto alto o se te indica la configuración adicional que necesitás para exponer el 8080 sin root. La gracia es que en vez de pasar veinte minutos tipeando archivos INI, pegás el YAML, revisás los warnings y ajustás lo que haga falta.

Tabla comparativa: docker-compose vs Podman Quadlet

Característica	Docker Compose	Podman Quadlet
Formato de archivo	YAML (estructura jerárquica)	INI con secciones (systemd)
Manejo de dependencias	depends_on con condiciones	Requires=/After=, sin equivalente nativo a service_healthy
Construcción de imagen	Soporta build desde Dockerfile	No soporta build; necesita imagen preconstruida
Gestión de volúmenes	Declarados junto con servicios	Archivo .volume separado y referenciado
Redes	Definidas en el mismo archivo	Archivo .network independiente
Ejecución sin root	Requiere configuración adicional	Nativo rootless, integrado con systemd del usuario
Secretos	Soporte nativo con secrets	No nativo; usar systemd-creds o bind mounts
Healthchecks	Integrados en el servicio	Soportados vía HealthCmd=, con misma semántica

Errores comunes al migrar (y cómo evitarlos)

1. Asumir que depends_on funciona igual que en Docker. Muchos copian la conversión automática y no revisan el Warning. En systemd, Requires= solo asegura que la unidad se inicie, pero no espera a que el servicio esté healthy. Si tu app necesita que MySQL responda consultas antes de arrancar, agregá un ExecCondition= o un script de verificación.

2. Olvidar el systemctl daemon-reload. Generás los archivos .container en ~/.config/containers/systemd/ (rootless) o en /etc/containers/systemd/ (rootful), pero los cambios no tienen efecto hasta que corrés systemctl --user daemon-reload o systemctl daemon-reload. Sin ese paso, el servicio no se entera de las nuevas unidades.

3. Usar puertos bajos en rootless sin configurar el socket. QuadletGen te ajusta los puertos, pero si necesitás exponer el 80 o 443 sin root, tenés que habilitar net.ipv4.ip_unprivileged_port_start=80 o usar un proxy inverso. La herramienta te lo advierte, pero suelen ignorarlo y después el contenedor no levanta. Cubrimos ese tema en detalle en cómo ejecutar agentes locales sin API.

Preguntas Frecuentes

¿Qué es Podman Quadlet y cómo funciona?

Podman Quadlet es el método nativo de systemd para ejecutar contenedores con Podman. En vez de escribir archivos YAML, definís unidades de systemd con extensiones .container, .volume y .network. Quadlet traduce esas definiciones a servicios systemd que manejan el ciclo de vida del contenedor, permitiéndote usar herramientas como systemctl y journald.

¿Cómo migrar de docker-compose a Podman Quadlet paso a paso?

Primero instalá Podman con soporte Quadlet (disponible en RHEL 9, CentOS Stream 9 y derivados). Luego, si querés automatizar, usá QuadletGen: pegá tu docker-compose.yml, elegí rootless o rootful, y descargá los archivos. Colocalos en la ruta correcta y ejecutá systemctl --user daemon-reload (o systemctl daemon-reload). Finalmente, iniciá los servicios con systemctl --user start nombre.container.

¿Cuál es la diferencia entre docker-compose y Podman Quadlet?

Docker Compose usa YAML y un motor propio para orquestar múltiples contenedores. Quadlet es una capa de systemd: cada contenedor es una unidad de systemd con sintaxis INI. Esto integra los contenedores al sistema de inicio estándar de Linux, facilita el logging con journald y permite dependencias finas entre servicios del sistema, pero pierde algunas funcionalidades como build o secrets nativos.

¿QuadletGen es gratuito y está disponible para todas las distribuciones?

Sí, es gratuito y funciona en cualquier navegador moderno porque corre del lado del cliente. No necesita instalación ni depende de una distribución en particular. Solo pegás el YAML y obtenés los archivos Quadlet, que luego podés usar en cualquier distro que tenga Podman con Quadlet habilitado (RHEL, Fedora, CentOS, etc.).

¿Qué limitaciones tiene Podman Quadlet frente a docker-compose?

No soporta construcción de imágenes (build), no maneja secrets de forma nativa, y la semántica de dependencias condicionales como depends_on con service_healthy no es idéntica. Tampoco ofrece un comando único para levantar todo un stack (tenés que habilitar e iniciar cada unidad por separado o usar un target de systemd). Sin embargo, para entornos de producción con systemd, suele ser más robusto que Compose.

Conclusión

QuadletGen no inventa la pólvora, pero soluciona el problema más irritante de la migración: la traducción manual de sintaxis. Al automatizar la conversión y darte un informe de cobertura con advertencias claras, te deja concentrarte en los puntos que de verdad necesitan tu criterio — como los healthchecks condicionales o la adaptación de secretos. Si estás moviendo stacks a Podman en 2026, tener esta herramienta a mano te ahorra horas y varios dolores de cabeza.

Pegale una mirada a QuadletGen, y si andás necesitando un VPS para probar tus containers en producción, podés levantar una máquina con CentOS Stream o RHEL en minutos y darle a systemd sin vueltas.

Fuentes

• Stop Hand-Translating docker-compose.yml to Podman Quadlet — Artículo original en dev.to
• QuadletGen — Herramienta oficial de conversión
• Documentación de Quadlet — Referencia de Podman sobre archivos .container, .volume y .network