Quarkus y Podman son una gran combinación para el desarrollo moderno. Sin embargo, hay un detalle poco visible que puede generar confusiones o errores, especialmente al trabajar con Dev Services o Testcontainers.
El problema: la forma en que Quarkus se conecta al motor de contenedores.
A diferencia de Docker, Podman requiere que especifiques explícitamente el socket a utilizar. Además, en algunos entornos es necesario desactivar un componente llamado Ryuk. Si nunca escuchaste hablar de Ryuk, no estás solo. Muchos desarrolladores (incluso con experiencia en Quarkus) descubren este tema recién cuando las pruebas fallan sin razón aparente.
En esta guía te mostramos cómo configurar correctamente tu entorno para que todo funcione desde el primer quarkus dev.
🦭 ¿Qué es Podman?
Podman es un motor de contenedores de código abierto con dos características distintivas:
- Daemonless: No requiere un proceso central corriendo en segundo plano (a diferencia de Docker).
- Rootless: Puede ejecutar contenedores sin privilegios de administrador.
Funciona en Linux, Windows y macOS, y es compatible con imágenes OCI (el mismo estándar que usa Docker).
Instalación recomendada
La forma más sencilla de instalar Podman es a través de Podman Desktop, que incluye tanto el motor como una interfaz gráfica para gestionar contenedores.
⚠️ En macOS: Se recomienda NO usar Homebrew para instalar Podman, ya que puede generar combinaciones de componentes no verificadas.
⚙️ Variables de entorno necesarias
Para que Quarkus, Dev Services y Testcontainers funcionen correctamente con Podman, necesitas configurar estas variables de entorno:
| Variable | Propósito |
|---|---|
DOCKER_HOST | Indica la ubicación del socket de Podman. El valor depende del sistema operativo (ver secciones más abajo). |
TESTCONTAINERS_RYUK_DISABLED=true | Desactiva Ryuk, un contenedor auxiliar de limpieza que no funciona bien con Podman. |
Además, crea el archivo ~/.testcontainers.properties con:
| Propiedad | Propósito |
|---|---|
docker.host | Misma ubicación del socket que DOCKER_HOST. |
testcontainers.reuse.enable | Controla si los contenedores se reutilizan entre reinicios (ver nota). |
💡 Sobre testcontainers.reuse.enable: Con true, el mismo contenedor se reutiliza entre reinicios de tu aplicación, acelerando el ciclo de desarrollo. El valor por defecto es false, por lo que no necesitas declararlo si prefieres un contenedor nuevo en cada ejecución. Ten en cuenta que la reutilización solo aplica si el contenedor sigue corriendo: si lo detienes con
podman stop, se creará uno nuevo (a menos que lo levantes manualmente antes de ejecutar tu aplicación).
🖥️ Configurando DOCKER_HOST por sistema operativo
🐧 Linux
Antes de configurar, necesitas saber en qué modo está corriendo tu Podman.
¿Rootless o rootful?
| Modo | ¿Qué significa? | ¿Cuándo se usa? |
|---|---|---|
| Rootless | Los contenedores corrensin privilegios de root . Más seguro. | Es el modo predeterminado en la mayoría de instalaciones modernas. |
| Rootful | Los contenedores correncon privilegios de root . Acceso completo al sistema. | Usado en servidores o cuando se necesita acceso a recursos del sistema. |
¿Cómo sé cuál estoy usando?
Ejecuta este comando:
podman info --format '{{.Host.Security.Rootless}}'- Si devuelve
true: Estás en modo rootless - Si devuelve
false: Estás en modo rootful
💡 Si no estás seguro, probablemente estés en modo rootless. Es el más común para desarrollo.
Modo rootless
Esta es la configuración más común. El socket de Podman no está en la ubicación estándar de Docker, por lo que hay que declararlo explícitamente.
1. Agrega a tu archivo de entorno (~/.bashrc o ~/.zshrc):
export DOCKER_HOST="unix://${XDG_RUNTIME_DIR}/podman/podman.sock"
export TESTCONTAINERS_RYUK_DISABLED=true2. Crea o edita ~/.testcontainers.properties:
docker.host=unix://${XDG_RUNTIME_DIR}/podman/podman.sock
testcontainers.reuse.enable=true3. Recarga tu shell:
source ~/.bashrc # o ~/.zshrcModo rootful
Si confirmaste que estás en modo rootful, verifica que el socket de compatibilidad Docker esté disponible:
ls -l /var/run/docker.sock- ✅ Si el archivo existe y apunta a
podman.sock: Usa la configuración de esta sección. - ❌ Si NO existe: Habilítalo con
sudo systemctl enable --now podman.socket, o usa la configuración rootless.
1. Agrega a tu archivo de entorno:
export DOCKER_HOST="unix:///var/run/podman.sock"
export TESTCONTAINERS_RYUK_DISABLED=true2. Crea o edita ~/.testcontainers.properties:
docker.host=unix:///var/run/podman.sock
testcontainers.reuse.enable=true🍎 macOS
En macOS, Podman corre dentro de una máquina virtual. El socket está dentro de esa VM, y hay que indicar su ubicación exacta.
💡 Recomendación: No dependas de
/var/run/docker.sock. ConfiguraDOCKER_HOSTexplícitamente para evitar ambigüedades.
1. Agrega a tu archivo de entorno (~/.zshrc):
export DOCKER_HOST="unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}')"
export TESTCONTAINERS_RYUK_DISABLED=true2. Crea o edita ~/.testcontainers.properties:
docker.host=unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}')
testcontainers.reuse.enable=true3. Recarga tu shell:
source ~/.zshrc🪟 Windows
En Windows, Podman corre dentro de una máquina virtual basada en WSL2 (Windows Subsystem for Linux). Podman Desktop se encarga de crear y gestionar esta VM automáticamente.
Requisitos previos:
- Windows 10/11 con WSL2 habilitado
- Podman Desktop instalado desde podman-desktop.io
1. Inicia Podman Desktop y asegúrate de que la máquina Podman esté corriendo (verás un indicador verde).
2. Configura las variables de entorno del sistema:
Abre PowerShell como administrador y ejecuta:
[System.Environment]::SetEnvironmentVariable("DOCKER_HOST", "npipe:////./pipe/podman-machine-default", "User")
[System.Environment]::SetEnvironmentVariable("TESTCONTAINERS_RYUK_DISABLED", "true", "User")3. Crea el archivo de configuración de Testcontainers:
En tu carpeta de usuario (C:\Users\TuUsuario\), crea un archivo llamado .testcontainers.properties con este contenido:
docker.host=npipe:////./pipe/podman-machine-default<br>testcontainers.reuse.enable=true4. Reinicia tu terminal o IDE para que las variables de entorno tomen efecto.
✅ Verificar que todo funciona
La mejor forma de probar la configuración es crear una aplicación con una extensión que use Dev Services:
quarkus create app podman-test -x oidc
cd podman-test
quarkus devAl ejecutar quarkus dev, Dev Services debería:
- Descargar la imagen de Keycloak
- Levantar un contenedor automáticamente
- Configurar tu aplicación para usarlo
Si ves Keycloak iniciando en los logs, ¡tu configuración está correcta! 🎉
🧭 Resumen rápido por sistema operativo
| Sistema | DOCKER_HOST |
|---|---|
| Linux (rootless) | unix://${XDG_RUNTIME_DIR}/podman/podman.sock |
| Linux (rootful) | unix:///var/run/podman.sock |
| macOS | unix://$(podman machine inspect --format '{{.ConnectionInfo.PodmanSocket.Path}}') |
| Windows | npipe:////./pipe/podman-machine-default |
En todos los casos, agrega también:
export TESTCONTAINERS_RYUK_DISABLED=true🚀 Conclusión
Con unas pocas líneas de configuración, puedes dejar tu entorno de desarrollo con Quarkus y Podman listo para despegar.
Lo mejor: evitas errores difíciles de rastrear que muchas veces se atribuyen al framework, cuando en realidad son producto de una integración no del todo ajustada.
¡Buen viaje! 🚀