Una máquina virtual completa dentro de Docker con interfaz web

A veces necesitas verificar rápidamente un script sospechoso, probar la instalación de software en una distribución limpia o desplegar un entorno con un kernel específico. Abrir VirtualBox para esto es demasiado tedioso, configurar Proxmox en una laptop de trabajo es overkill, y un contenedor Docker normal no proporciona aislamiento a nivel de kernel.

Hace poco encontré un repositorio qemus/qemu. El proyecto empaqueta QEMU con aceleración KVM dentro de un contenedor Docker normal y expone la gestión de VMs directamente en el navegador.

Cómo funciona el proyecto

Básicamente, esto es un wrapper alrededor de QEMU que maneja toda la configuración tediosa del emulador, redes, discos y cliente noVNC. No necesitas escribir manualmente flags largos de línea de comandos ni pelear con configs XML libvirt.

Toda la gestión se reduce a pasar variables de entorno a docker-compose.yml. La imagen descarga automáticamente la distribución Linux requerida, crea un disco virtual, conecta KVM para un rendimiento casi nativo, y abre la interfaz web en el puerto 8006.

El contenedor es adecuado tanto para desarrollo local como para ejecutar VMs en Kubernetes o GitHub Codespaces.

Inicio rápido

Para lanzarlo, solo necesitas un archivo compose mínimo. Por ejemplo, despleguemos Linux Mint:

services:
  qemu:
    image: qemux/qemu
    container_name: qemu
    environment:
      BOOT: "mint"
      RAM_SIZE: "4G"
      CPU_CORES: "2"
    devices:
      - /dev/kvm
      - /dev/net/tun
    cap_add:
      - NET_ADMIN
    ports:
      - 8006:8006
    volumes:
      - ./qemu_data:/storage
    restart: always
    stop_grace_period: 2m

Después de ejecutar docker compose up -d, el servicio descarga automáticamente el ISO de Mint e inicia la virtualización.

Navega a http://localhost:8006 en tu navegador y verás la pantalla de instalación del SO. No es necesario instalar clientes VNC adicionales.

# Если вы предпочитаете чистый Docker CLI:
docker run -it --rm --name qemu \
  -e "BOOT=alpine" \
  -p 8006:8006 \
  --device=/dev/kvm \
  --device=/dev/net/tun \
  --cap-add NET_ADMIN \
  -v "${PWD}/qemu_data:/storage" \
  --stop-timeout 120 \
  docker.io/qemux/qemu

Qué puede hacer el contenedor

Descarga automática de distribuciones

En la variable BOOT, puedes especificar un nombre corto de una distribución popular. El script sabe dónde obtener las imágenes más recientes:

• arch, debian, fedora, ubuntu, alpine
• kali, nixos, gentoo, mint, manjaro
• rocky, alma, cachy, tails

Si el sistema que necesitas no está en la lista predefinida, puedes pasar un enlace directo a cualquier imagen:

environment:
  BOOT: "https://dl-cdn.alpinelinux.org/alpine/v3.19/releases/x86_64/alpine-virt-3.19.1-x86_64.iso"

El contenedor descomprime archivos sobre la marcha y soporta imágenes en formatos .iso, .qcow2, .vmdk, .vhdx y .vdi. También puedes montar un archivo local directamente en la raíz del contenedor como /boot.iso.

Trabajando con discos y memoria

Por defecto, la VM obtiene un disco de 64 GB en formato qcow2 dentro del directorio /storage. Puedes cambiar el tamaño en cualquier momento mediante la variable DISK_SIZE: "128G".

Si el host se queda sin RAM, el contenedor soporta memory ballooning. Esto ayuda a devolver dinámicamente la memoria no utilizada del guest al host.

Compartir archivos con el host

Para transferir archivos entre el host y la VM, se usa el protocolo 9pfs:

volumes:
  - ./my_host_folder:/shared

Dentro del sistema guest en ejecución, solo necesitas montar el directorio:

mount -t 9p -o trans=virtio shared /mnt/shared

Reenvío de puertos y red completa

Con el modo bridge estándar de Docker, el reenvío de puertos se configura mediante el familiar bloque ports. Para reenviar SSH externamente:

ports:
  - 8006:8006
  - 2222:22

Si la VM necesita su propia dirección IP en la red local (para que el router de casa le asigne una dirección separada vía DHCP), el contenedor puede conectarse vía macvlan. En este caso, no es necesario el mapeo constante de puertos.

Passthrough de hardware real

A través del archivo compose, puedes hacer passthrough de discos físicos reales (/dev/sdb:/disk1) o dispositivos USB pasando sus identificadores a QEMU:

environment:
  ARGUMENTS: "-device usb-host,vendorid=0x1234,productid=0x5678"
devices:
  - /dev/bus/usb

Requisitos del sistema y limitaciones

La principal limitación está en el soporte de KVM.

Sin acceso directo al dispositivo /dev/kvm, la aceleración de hardware no funcionará, y la emulación por software de la CPU hará que el rendimiento sea insoportablemente lento.

Dónde funciona sin problemas:

1. Hosts Linux con soporte de virtualización por hardware (Intel VT-x / AMD-V).
2. Windows 11 con Docker Desktop o Podman Desktop con virtualización anidada habilitada.

Docker Desktop en macOS y Windows 10 actualmente no pasa /dev/kvm a los contenedores, así que no podrás ejecutar el proyecto allí.

Puedes verificar la disponibilidad de KVM en Linux con la utilidad estándar:

sudo apt install cpu-checker
sudo kvm-ok

Si el comando muestra KVM acceleration can be used, el contenedor se iniciará sin problemas.

Para qué puedes usar esto

1. Escenarios de prueba de automatización. Ejecutar instalaciones limpias de Ansible o scripts bash en una VM aislada sin arriesgar romper tu sistema de trabajo.
2. Ejecución segura de software. Verificar paquetes o binarios sospechosos en un entorno aislado que puede recrearse con un solo comando.
3. Aprendizaje y experimentos. Explorar nuevas distribuciones (p. ej., NixOS o Alpine) directamente en la ventana del navegador sin lidiar con unidades USB.
4. Pipelines de CI/CD. Construir paquetes de kernel o probar software del sistema dentro de máquinas virtuales completas en runners de Kubernetes.

Resumen

El proyecto qemus/qemu llena perfectamente el nicho entre contenedores ligeros e hipervisores pesados. Si regularmente necesitas máquinas virtuales aisladas para pruebas en una máquina Linux o servidor de casa, esta imagen ahorra mucho tiempo en preparación de imágenes y configuración de red.

El repositorio es mantenido activamente por la organización qemus, que también tiene builds adaptados separados para ARM64, Windows y macOS.