Quarkus y Podman son una gran combinación para el desarrollo moderno con contenedores. Sin embargo, hay un detalle poco visible que puede generar confusiones o errores, especialmente al trabajar con Dev Services o Testcontainers: la forma en que se conectan al daemon de contenedores.
A diferencia de Docker, Podman requiere que especifiques explícitamente el socket a utilizar, y en algunos entornos también es necesario desactivar un componente llamado Ryuk. Si nunca escuchaste hablar de Ryuk, no estás solo ya que muchos desarrolladores (incluso con experiencia en Quarkus) descubren este tema recién cuando las pruebas fallan sin razón aparente.
Distintas voces de la comunidad, incluyendo artículos técnicos, comentarios en GitHub y hasta una mención en el blog oficial de Quarkus, coinciden en que el soporte de Ryuk con Podman puede ser inestable y que vale la pena ajustar el entorno desde el principio.
En esta guía te mostramos cómo configurar correctamente tu entorno para que todo funcione como esperas desde el primer quarkus dev.
Instalar Podman y Podman Desktop
Podman es un motor de contenedores de código abierto, es daemonless (no requiere un proceso central en segundo plano para gestionar contenedores) and rootless (sin privilegios de root), para desarrollar, administrar y ejecutar contenedores OCI en Linux, Windows y Mac.
Y por otro lado tenemos a Podman Desktop que es una herramienta de código abierto y gratuita que proporciona una interfaz gráfica para gestionar contenedores, pods e imágenes de contenedor. Puedes descargar Podman Desktop aquí (incluye Podman)
⚠️ Si usas MacOS se recomienda no usar Homebrew para instalar Podman ya que genera una combinación de componentes no verificada.
Configurar Podman para Quarkus
Veamos en detalle las configuraciones necesarias:
DOCKER_HOST
Le dice a Quarkus y a las bibliotecas subyacentes dónde encontrar el socket de Podman. Sin esto, pueden fallar silenciosamente o buscar un demonio Docker que no existe.TESTCONTAINERS_RYUK_DISABLED=true
Previene errores al deshabilitar Ryuk (un contenedor auxiliar que intenta limpiar recursos, pero que con Podman tiende a fallar). Deshabilitarlo mejora la estabilidad y evita errores confusos.testcontainers.reuse.enable=false
Garantiza que cada ejecución de pruebas arranque con contenedores nuevos, evitando residuos que podrían afectar la confiabilidad de los tests en Quarkus.
A continuación, elige la configuración según tu sistema operativo y la modalidad de Podman que uses.
Linux (rootless)
Si usas Podman en Linux en modo rootless (la configuración predeterminada en muchos entornos), el socket que necesitan Quarkus y Testcontainers no está en la ubicación estándar de Docker. Por eso, hay que declararlo explícitamente.
En tu archivo de entorno (~/.bashrc, ~/.zshrc, etc.):
export DOCKER_HOST="unix://${XDG_RUNTIME_DIR}/podman/podman.sock"
export TESTCONTAINERS_RYUK_DISABLED=trueEn ~/.testcontainers.properties (si no existe, debes crearlo) agrega las siguientes propiedades:
docker.host=unix://${XDG_RUNTIME_DIR}/podman/podman.sock
testcontainers.reuse.enable=falseLinux ( rootful – con socket en /var/run/podman.sock)
Si estás usando Podman en Linux con privilegios (modo rootful) y activaste el acceso al socket de contenedores en /var/run/podman.sock, es posible que estés usando lo que se conoce como modo Docker-compatible. Esto se puede habilitar manualmente desde la terminal, aunque en algunos entornos (como Podman Desktop) puede venir preconfigurado o activarse desde la interfaz.
Una forma rápida de comprobar si está activado, es ejecutar este comando en la terminal:
ls -l /var/run/docker.sockSi el resultado muestra que ese archivo existe y apunta a un socket de Podman (termina en podman.sock), entonces ya estás usando esta compatibilidad. Lo importante es saber que si ese socket está disponible, los ajustes cambian ligeramente:
En tu archivo de entorno (~/.bashrc, ~/.zshrc, etc.):
export DOCKER_HOST="unix:///var/run/podman.sock"
export TESTCONTAINERS_RYUK_DISABLED=true
En ~/.testcontainers.properties (si no existe, debes crearlo) agrega las siguientes propiedades:
Si el archivo no existe, debes crearlo. Agrega las siguientes propiedades:
docker.host=unix:///var/run/podman.sock
testcontainers.reuse.enable=falsemacOS
En macOS, Podman no corre directamente sobre el sistema operativo, sino dentro de una máquina virtual. Esto implica que el socket también está dentro de esa VM, y hay que indicar su ubicación exacta.
Para evitar confusiones y asegurarte de que todo funcione como esperás, en macOS recomendamos no depender de /var/run/docker.sock y establecer manualmente la ruta del socket de Podman con DOCKER_HOST. De este modo, Dev Services, Quarkus CLI, Testcontainers y los plugins de Maven sabrán a dónde conectarse sin ambigüedades.
En tu archivo de entorno (~/.bashrc, ~/.zshrc, etc.):
export DOCKER_HOST="unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}')"
export TESTCONTAINERS_RYUK_DISABLED=true
En ~/.testcontainers.properties (si no existe, debes crearlo) agrega las siguientes propiedades:
Si el archivo no existe, debes crearlo. Agrega las siguientes propiedades:
docker.host=unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}')
testcontainers.reuse.enable=false✅ Verificar la configuración de Podman
Ejecuta el siguiente comando que crea una aplicación Quarkus con la extension oidc.
quarkus create app podman-test -x oidc && cd podman-test && quarkus devAl ejecutar quarkus dev, Dev Services obtiene la imagen y levanta un contenedor de Keyclock en Podman.
En resumen
Como has visto, con unas pocas líneas de configuración puedes dejar tu entorno de desarrollo con Quarkus y Podman listo para despegar. Y lo mejor: evitas errores difíciles de rastrear y comportamientos extraños que muchas veces se atribuyen al framework, cuando en realidad son producto de una integración no del todo ajustada. ¡Buen viaje! 🚀