Actualizado: 2026-07-07

Instalar Docker en Debian 12 parece un trámite mecánico: copias cuatro comandos y listo. Pero hay decisiones ocultas en ese proceso que condicionan los próximos doce meses de operación. Qué repositorio usar, cómo gestionar los permisos y qué poner en daemon.json desde el primer arranque son preguntas con consecuencias reales en cuanto la máquina pasa de experimento a servicio expuesto.

Puntos clave

  • El paquete docker.io de Debian va varios minors por detrás; el repositorio oficial de Docker es la única elección razonable para producción.

  • La instalación estándar requiere cinco paquetes: docker-ce, docker-ce-cli, containerd.io, docker-buildx-plugin y docker-compose-plugin.

  • Pertenecer al grupo docker equivale a tener root en la máquina; evalúa Docker rootless en servidores compartidos.

  • Configura rotación de logs y live-restore en daemon.json desde el primer día para evitar los problemas más comunes.

  • docker run hello-world que imprime el mensaje verde es el principio, no el final.

Por qué no usar el paquete de Debian

Debian incluye docker.io en sus repositorios, y para jugar en un portátil es aceptable. El propio wiki de Debian sobre Docker[1] lo deja claro: docker.io es el paquete de la distribución y docker-ce es el equivalente que mantiene el proyecto Docker. Cuando la máquina hace trabajo real, el paquete de la distribución se queda corto:

  • La versión empaquetada va varios minors por detrás de la rama estable.

  • Los parches de seguridad tardan más en aparecer.

  • Los componentes (motor, CLI, containerd, BuildKit) no se actualizan de forma coordinada.

El repositorio oficial de Docker resuelve los tres problemas: recibes la versión actual, los parches llegan el mismo día que se publican y los componentes se actualizan como un conjunto coherente. Este tutorial sigue la guía oficial de instalación para Debian[2] sobre Debian 12 «Bookworm», publicado el 10 de junio de 2023 según la página oficial de la versión[3]. Además, el plugin docker compose v2 viene empaquetado junto al motor, eliminando el baile histórico entre docker-compose con guión y docker compose con espacio.

Preparar el terreno

Antes de añadir nada nuevo, retira cualquier instalación previa:

sudo apt-get remove docker docker-engine docker.io containerd runc

Esto limpia los binarios sin tocar imágenes ni volúmenes en /var/lib/docker y /var/lib/containerd. Con el sistema limpio, actualiza APT e instala las dependencias mínimas para añadir un repositorio firmado:

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

Clave GPG y repositorio

El método moderno de Debian para añadir claves de repositorios es depositarlas en /etc/apt/keyrings/ como ficheros individuales. El viejo apt-key add lleva años marcado como deprecado porque una clave instalada globalmente firma implícitamente cualquier repositorio, rompiendo el aislamiento que APT intenta ofrecer.

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | 
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo 
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] 
  https://download.docker.com/linux/debian 
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | 
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

La directiva signed-by= hace la clave exclusiva de ese repositorio: APT solo aceptará firmas de Docker para paquetes de download.docker.com.

Logotipo de Bash, el intérprete de comandos con el que ejecutamos todos los pasos de instalación de Docker en DebianLogotipo de Bash, el intérprete de comandos con el que ejecutamos todos los pasos de instalación de Docker en Debian

Instalar los paquetes correctos

Docker no es un único binario sino un conjunto de piezas con funciones distintas:

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io 
  docker-buildx-plugin docker-compose-plugin

Qué hace cada uno:

  • docker-ce: el daemon dockerd que escucha en el socket Unix y orquesta contenedores.

  • docker-ce-cli: el cliente docker que habla con el daemon.

  • containerd.io: el runtime de bajo nivel que lanza los contenedores.

  • docker-buildx-plugin: construcción multiplataforma con BuildKit.

  • docker-compose-plugin: orquestador declarativo v2.

Al terminar, systemd arranca el servicio y lo deja en estado enabled.

Verificación y grupo docker

Tres comandos confirman que todo está en su sitio:

docker --version
docker compose version
docker run hello-world

Si el último falla pero los dos primeros funcionan, el problema suele estar en DNS o en el registry, no en la instalación.

Añadir tu usuario al grupo docker parece cosmético pero tiene implicaciones de seguridad serias, algo que el propio wiki de Debian[1] resume diciendo que pertenecer al grupo es más peligroso que tener acceso a sudo. Pertenecer al grupo equivale prácticamente a tener root en la máquina: quien puede ejecutar docker run puede montar el sistema de ficheros raíz dentro de un contenedor privilegiado. En servidor compartido, evalúa Docker rootless[4]. En servidor personal, el grupo es aceptable si conoces el compromiso.

sudo usermod -aG docker $USER
newgrp docker

Configuración que evita sorpresas

El fichero /etc/docker/daemon.json viene vacío por defecto. Dejarlo así es el primer error de producción que comete casi todo el mundo. Dos parámetros que merecen estar desde el primer día:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  },
  "live-restore": true
}

Sin rotación de logs, un contenedor locuaz llena el disco en días: el ejemplo anterior limita cada fichero a 10 MB y conserva un máximo de 3 en rotación. Con live-restore[5], los contenedores sobreviven a un reinicio del daemon, así que las actualizaciones de Docker dejan de tumbar los servicios. Aplica los cambios con sudo systemctl reload docker.

Logotipo de Prometheus, herramienta de métricas que puedes usar para monitorizar el estado del daemon Docker en producciónLogotipo de Prometheus, herramienta de métricas que puedes usar para monitorizar el estado del daemon Docker en producción

Problemas que aparecen siempre

  • permission denied al invocar docker sin sudo: el cambio de grupo no se aplicó a la sesión. newgrp docker lo resuelve.

  • Cannot connect to the Docker daemon: dockerd no está corriendo. systemctl status docker y journalctl -u docker -n 100 revelan la causa.

  • Pulls lentos: Docker Hub limita las descargas anónimas[6] a 100 cada 6 horas, o hay problemas de DNS. Un registry-mirrors local es el remedio.

  • Disco lleno: docker system prune -a --volumes libera espacio agresivamente, incluyendo volúmenes anónimos: ten cuidado.

Conclusión

Lo que separa una instalación viable de una que morderá en seis meses no son los comandos del repositorio oficial, sino las decisiones que tomas justo después. Configura la rotación de logs desde el primer día. Activa live-restore. Entiende qué implica el grupo docker. Ninguna de estas cosas aparece en los tutoriales de cinco minutos, y todas importan más que el orden exacto de los paquetes.

Con el daemon funcionando, el siguiente paso natural suele ser una interfaz de gestión: cómo instalar Portainer con Docker Compose v2. Si el plan es usar el servidor con Docker Swarm, el paso siguiente es cuándo Docker Swarm sigue teniendo sentido.

Lee también la versión en inglés: How to Install Docker on Debian 12 Step by Step.

Preguntas frecuentes

¿Necesito desinstalar docker.io antes de instalar Docker CE en Debian 12?

Sí. Ejecuta sudo apt-get remove docker docker-engine docker.io containerd runc antes de añadir el repositorio oficial. Los dos paquetes compiten por el mismo socket y los mismos ficheros de servicio, así que dejarlos coexistir provoca arranques inconsistentes.

¿Por qué pertenecer al grupo docker es un riesgo de seguridad?

Porque cualquier cuenta con acceso al socket de Docker puede montar el sistema de ficheros raíz dentro de un contenedor privilegiado, lo que equivale a tener root en la máquina. En un servidor compartido, la alternativa razonable es Docker rootless.

¿Qué hago si docker run hello-world falla tras la instalación?

Si docker --version y docker compose version responden bien pero el hello-world falla, el problema casi siempre es de red (DNS o acceso al registry), no de la instalación de los paquetes en sí.

Fuentes

  1. wiki de Debian sobre Docker
  2. guía oficial de instalación para Debian
  3. página oficial de la versión
  4. Docker rootless
  5. live-restore
  6. limita las descargas anónimas