Cuando ejecutaste docker run hello-world en la lección anterior, el propio mensaje del contenedor te resumió lo que había ocurrido: el cliente contactó con el daemon, el daemon descargó una imagen del registro, creó un contenedor a partir de ella y te devolvió su salida. Esa frase esconde una arquitectura completa, y entenderla es lo que separa a quien memoriza comandos de quien sabe diagnosticar problemas. En esta lección vas a abrir la caja: descubrirás que docker no ejecuta contenedores (solo los pide), quién los ejecuta realmente, qué papel juegan containerd y runc, qué es ese socket del que tanto hablamos y por qué el daemon es el verdadero dueño de todas tus imágenes, contenedores, volúmenes y redes. Terminarás interpretando la salida real de docker info y docker system df con ojos nuevos.

1. Docker es cliente-servidor, no un programa
2. El cliente docker
3. El daemon dockerd
4. La API REST y el socket /var/run/docker.sock
5. El flujo completo de un docker run
6. containerd y runc: por qué hay tres capas
7. Los objetos que gestiona el daemon
8. Los registros y su papel
9. Demostración práctica: docker info y docker system df

El primer malentendido que hay que deshacer: cuando escribes docker run, ese comando no crea ningún contenedor. Lo único que hace es traducir tu orden a una petición HTTP y enviarla a otro proceso, que es el que hace el trabajo de verdad.

Docker sigue una arquitectura cliente-servidor con tres actores:

Las consecuencias de este diseño son muy prácticas:

• El cliente puede estar en otra máquina que el daemon. Puedes gestionar un servidor remoto desde tu portátil con el mismo comando docker.
• Puede haber muchos clientes contra un mismo daemon. Tu terminal, tu IDE y una herramienta de CI pueden hablar con el mismo motor a la vez.
• Si el daemon está parado, el cliente no puede hacer nada. De ahí el famoso Cannot connect to the Docker daemon.
• El estado vive en el daemon, no en tu terminal. Cerrar la terminal no para tus contenedores.

El cliente es sorprendentemente tonto, y eso es bueno. Sus responsabilidades son:

1. Parsear lo que escribes (docker run -d --name web nginx).
2. Convertirlo en una o varias llamadas a la API REST del daemon.
3. Mostrarte la respuesta con formato legible.

Nada más. No sabe crear contenedores, ni descomprimir imágenes, ni hablar con el kernel.

El cliente decide a qué daemon habla mediante los llamados contextos. Puedes verlos así:

Lectura: hay un único contexto, default, marcado como activo con el asterisco, y apunta al socket Unix local. Si tuvieras un servidor remoto configurado, verías otra fila con un DOCKER ENDPOINT del tipo ssh://usuario@servidor.

También puedes forzar el destino con la variable de entorno DOCKER_HOST:

Este comando lista los contenedores del servidor remoto, no los tuyos. El cliente es exactamente el mismo binario; solo cambia con quién habla. Es una demostración perfecta de que el cliente no ejecuta nada.

dockerd es el proceso que hace el trabajo. Corre como servicio del sistema (en Linux, gestionado por systemd) con privilegios de root, porque necesita manipular el kernel: crear espacios de nombres, configurar interfaces de red virtuales, montar sistemas de archivos.

Puedes verlo con las herramientas normales del sistema:

La primera línea te muestra el estado del servicio (active (running)); la segunda, el proceso real y sus argumentos. Verás algo como /usr/bin/dockerd -H fd:// --containerd=/run/containerd/containerd.sock, donde -H fd:// indica que escucha en el socket que le pasa systemd y --containerd= señala con qué containerd habla (lo veremos en el apartado 6).

Sus responsabilidades:

• Exponer la API REST y atender a los clientes.
• Gestionar el ciclo de vida de imágenes, contenedores, volúmenes y redes.
• Descargar y subir imágenes desde y hacia los registros.
• Construir imágenes (delegando en BuildKit, tema del módulo 2 y de la lección 05-05).
• Configurar la red virtual de los contenedores.
• Delegar la ejecución real en containerd.

Un detalle importante: si dockerd se reinicia, tus contenedores no tienen por qué morir. Gracias a la separación con containerd que verás enseguida, los contenedores en ejecución pueden sobrevivir a un reinicio del daemon.

Toda la comunicación entre el cliente y el daemon es una API REST sobre HTTP. Lo llamativo es que, por defecto, ese HTTP no viaja por la red: viaja por un socket Unix, un fichero especial del sistema de archivos:

Léelo con atención, porque explica cosas de la lección anterior:

• La s inicial indica que es un socket, no un fichero normal.
• El propietario es root y el grupo es docker.
• Los permisos rw-rw---- significan: root puede leer y escribir, el grupo docker también, y nadie más.

Ahí está, en una línea, por qué necesitabas sudo o pertenecer al grupo docker. Y también por qué pertenecer al grupo docker equivale a ser root: quien puede escribir en ese socket puede pedirle al daemon (que es root) lo que quiera.

Que la API sea HTTP tiene una consecuencia divertida: puedes hablar con Docker sin usar el cliente. Con curl:

Qué acabas de hacer: --unix-socket le dice a curl que en vez de abrir una conexión TCP use ese fichero socket; http://localhost/version es la ruta del endpoint (el host es irrelevante, solo hace falta para formar una URL válida). La respuesta es JSON crudo: exactamente lo mismo que docker version te muestra bonito.

Otro ejemplo, listando contenedores:

Devuelve un array JSON con los contenedores en ejecución: el equivalente exacto de docker ps. Esto no es un truco de fiesta: es cómo funcionan por dentro las herramientas gráficas, los plugins de IDE y los sistemas de monitorización.

Advertencia de seguridad. Montar /var/run/docker.sock dentro de un contenedor es una práctica que verás en tutoriales (herramientas de CI, dashboards). Equivale a darle root sobre el anfitrión a ese contenedor. Se trata en detalle en la lección 05-03.

El daemon puede además escuchar en TCP (-H tcp://0.0.0.0:2376), imprescindible para acceso remoto, pero nunca sin TLS y autenticación: un daemon expuesto sin proteger en Internet se compromete en minutos.

Ahora sí, el recorrido completo de la orden más habitual del curso:

Paso a paso, en palabras:

1. Tú escribes el comando. El cliente lo parsea y valida las opciones.
2. El cliente llama a la API. Traduce tu orden a peticiones HTTP contra el socket.
3. El daemon busca la imagen en local. Si nginx:alpine ya está descargada, salta al paso 5.
4. Si falta, el daemon contacta con el registro. Pide primero el manifiesto (la lista de capas que componen la imagen) y luego descarga las capas que no tenga ya. Son estas descargas las que ves como Pull complete.
5. El daemon crea el contenedor. Prepara su sistema de archivos apilando las capas de la imagen y añadiendo encima una capa de escritura, reserva el nombre aurora-web-demo, y configura la red virtual y la regla de mapeo del puerto 8080 del host al 80 del contenedor.
6. El daemon pide a containerd que lo arranque.
7. containerd invoca a runc, que es quien realmente le dice al kernel: crea estos espacios de nombres, aplica estos límites de recursos, monta este sistema de archivos y lanza este proceso.
8. runc termina y desaparece. Su trabajo era arrancar el proceso, no supervisarlo.
9. El daemon devuelve el ID al cliente, que te lo imprime.

Que runc desaparezca tras arrancar el contenedor es la razón de que Docker pueda actualizarse o reiniciarse sin matar contenedores: el proceso del contenedor ya no cuelga de él.

A primera vista, tres componentes para arrancar un proceso parece exagerado. La razón es histórica y estratégica.

En los primeros años, Docker era un binario monolítico que lo hacía todo. A medida que los contenedores se convirtieron en infraestructura crítica, la industria pidió estándares para no depender de un único proveedor. De ahí nació la OCI (Open Container Initiative), que publicó dos especificaciones clave:

• OCI Image Spec: cómo se estructura una imagen (capas, manifiesto, configuración).
• OCI Runtime Spec: cómo se describe y arranca un contenedor a partir de un sistema de archivos y un fichero de configuración JSON.

Docker se troceó para encajar en esos estándares:

Míralo como una cadena de delegación, cada eslabón más específico y más simple que el anterior:

Ese containerd-shim intermedio es la pieza que explica el "reinicio sin muertes": hay un shim por contenedor que se queda vivo supervisándolo, recoge su código de salida y mantiene abiertos sus flujos de entrada/salida, de modo que ni dockerd ni runc necesitan seguir presentes.

¿Por qué te importa esto como usuario?

• Porque containerd es hoy un estándar del ecosistema, y lo usan otras plataformas directamente (Kubernetes, por ejemplo, habla con containerd sin pasar por Docker). Lo verás en el módulo 6.
• Porque explica que existan alternativas compatibles a Docker que ejecutan exactamente las mismas imágenes (tema de la lección 07-05).
• Porque cuando leas un error que mencione containerd o runc, sabrás a qué nivel está fallando algo.

Lo que ocurre exactamente en la flecha final —qué son los namespaces, los cgroups y cómo se apilan las capas del sistema de archivos— es el contenido de la lección 05-07. Aquí nos quedamos en el mapa.

El daemon mantiene cuatro tipos de objeto. Todo lo que harás en el curso es crear, listar, inspeccionar y borrar objetos de estos cuatro tipos, y la CLI moderna está organizada literalmente así (lo verás en la lección 01-04).

Todos ellos se materializan en el disco bajo el directorio de datos del daemon, normalmente /var/lib/docker:

Qué es cada cosa relevante:

• overlay2: las capas de las imágenes y las capas de escritura de los contenedores. Es lo que más ocupa con diferencia.
• image: los metadatos que relacionan imágenes con sus capas.
• containers: configuración y logs de cada contenedor.
• volumes: los datos de los volúmenes.
• network: la configuración de las redes virtuales.
• buildkit: la caché de construcción de imágenes.

Regla de oro: nunca toques a mano nada de /var/lib/docker. El daemon mantiene ahí bases de datos internas de estado; editar o borrar ficheros directamente es la forma más rápida de corromper la instalación. Todo se gestiona con comandos.

Un registro es un servicio que almacena y distribuye imágenes. Es la tercera pata de la arquitectura y la que da a Docker su capacidad de distribución.

El registro por defecto es Docker Hub (docker.io). Cuando escribes docker pull nginx:alpine, el cliente completa silenciosamente el nombre:

Donde docker.io es el registro, library es el espacio de nombres de las imágenes oficiales y nginx el repositorio. Por eso en la salida de hello-world viste Pulling from library/hello-world.

Para usar otro registro basta con nombrarlo explícitamente:

• El primero descarga del GitHub Container Registry.
• El segundo, de un registro privado autoalojado en la red de la empresa, que escucha en el puerto 5000.

Tipos habituales de registro:

El papel del registro en la arquitectura es el de almacén y punto de intercambio: el daemon sube (push) y baja (pull) imágenes, pero no lo necesita para ejecutar lo que ya tiene descargado. Un servidor sin conexión a Internet puede levantar contenedores perfectamente si sus imágenes ya están en local.

La autenticación (docker login), la publicación y la organización de repositorios se tratan en el módulo 2, especialmente en las lecciones 02-01 y 02-06.

Vamos a leer la arquitectura reflejada en la salida real de dos comandos.

Ahora que conoces la arquitectura, cada bloque tiene sentido:

En Windows o macOS, fíjate en que Operating System y Kernel Version no son los de tu equipo, sino los de la máquina virtual Linux de Docker Desktop. Es la demostración más clara de lo que se explicó en la lección 01-02.

Este comando responde a "¿en qué se me está yendo el disco?". Columna a columna:

• TYPE: los tipos de objeto del apartado 7, más la caché de construcción.
• TOTAL: cuántos objetos hay de ese tipo.
• ACTIVE: cuántos están en uso. Una imagen está activa si algún contenedor (aunque esté parado) la usa; un volumen, si está montado por algún contenedor.
• SIZE: espacio total ocupado. Ojo: en Images, este número tiene en cuenta que las capas compartidas se cuentan una sola vez (lección 01-05).
• RECLAIMABLE: cuánto recuperarías limpiando lo no usado. En el ejemplo, 1,376 GB de imágenes que ningún contenedor referencia.

Para el detalle por objeto:

Añade tablas desglosadas: cada imagen con su tamaño y cuántos contenedores la usan, cada contenedor con el tamaño de su capa de escritura, cada volumen con sus enlaces. Es la herramienta para localizar al culpable concreto de un disco lleno.

La limpieza (docker system prune) la verás en la lección 01-04.

• Creer que docker "es" Docker. El comando es solo un cliente. Si te acostumbras a pensar "yo pido, el daemon hace", entenderás por qué el daemon puede estar en otra máquina, por qué cerrar la terminal no para nada y por qué el estado no está donde escribes.
• Confundir "no encuentro el contenedor" con "no existe". Si tienes varios contextos o un DOCKER_HOST puesto en el entorno, puedes estar consultando otro daemon. Verifícalo con docker context ls y echo $DOCKER_HOST.
• Exponer el daemon por TCP sin TLS. Abrir -H tcp://0.0.0.0:2375 es entregar la máquina. Existen botnets que rastrean ese puerto continuamente. Si necesitas acceso remoto, usa el contexto por SSH (docker context create --docker host=ssh://...), que es simple y seguro.
• Montar /var/run/docker.sock dentro de un contenedor a la ligera. Es una escalada a root del anfitrión. A veces es necesario, pero debe ser una decisión consciente (lección 05-03).
• Tocar /var/lib/docker a mano. Borrar directorios ahí para "liberar espacio" corrompe el estado del daemon. Usa siempre los comandos de la CLI.
• Consejo: docker info es tu primer diagnóstico. Ante cualquier comportamiento raro, mira ahí: versión, driver de almacenamiento, cgroups, arquitectura y espacio. Muchos problemas "misteriosos" se explican con una línea de esa salida.
• Consejo: recuerda la cadena de delegación. dockerd → containerd → shim → runc → kernel. Con ese esquema en la cabeza, los mensajes de error de bajo nivel dejan de ser ruido.

Sin ejecutar ningún comando docker (salvo para comparar al final), consigue mediante curl sobre el socket Unix: (a) la versión del daemon, (b) el número de contenedores en ejecución, y (c) la lista de imágenes locales. Después, compara cada resultado con su comando docker equivalente y explica qué relación hay entre ambos.

Ejecuta estos comandos y responde a las preguntas:

(a) ¿Qué cifras cambian y por qué? (b) ¿Cuántos objetos de tipo imagen hay ahora activos y cuántos totales? (c) Si RECLAIMABLE de imágenes es alto, ¿qué significa exactamente eso en términos de la arquitectura que has estudiado?

Para cada uno de estos tres síntomas, indica en qué punto exacto de la cadena cliente → API/socket → daemon → registro → containerd → runc → kernel está el problema, y qué comprobarías:

1. Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
2. Error response from daemon: pull access denied for aurora-api, repository does not exist or may require 'docker login'
3. docker: Error response from daemon: driver failed programming external connectivity on endpoint aurora-web-demo: Bind for 0.0.0.0:8080 failed: port is already allocated.

Solución al ejercicio 1

Comentarios:

• -s silencia la barra de progreso de curl para dejar solo el JSON.
• --unix-socket es lo que hace posible todo: en lugar de una conexión TCP, curl escribe HTTP directamente en el fichero socket. El http://localhost es solo un relleno sintáctico para formar una URL válida; el nombre de host se ignora.
• /v1.49/ es la versión de la API; puedes omitirla y el daemon usará la más reciente que soporte. Si tu versión difiere, mírala en la salida de docker version (campo API version).
• En (b), el grep -o '"Id"' | wc -l cuenta cuántos objetos trae el array. Con jq instalado sería más limpio: | jq 'length'.

Los equivalentes son docker version, docker ps y docker image ls. La relación es directa: el cliente docker hace exactamente estas mismas llamadas HTTP y se limita a formatear la respuesta en tablas legibles. Comprobarlo de primera mano es la mejor forma de interiorizar que el cliente no ejecuta nada.

Solución al ejercicio 2

(a) Cambian dos cosas en la fila Images: el TOTAL sube en 1 (hay una imagen más) y el SIZE aumenta, pero normalmente menos que el tamaño anunciado de la imagen, porque las capas que ya tuvieras de otras imágenes basadas en Alpine no se descargan ni se cuentan dos veces. Además, RECLAIMABLE sube en el tamaño de la nueva imagen, porque acabas de descargarla y todavía ningún contenedor la usa.

(b) TOTAL es el número de imágenes almacenadas; ACTIVE cuenta solo las referenciadas por algún contenedor (aunque esté parado). La recién descargada suma al total pero no a las activas.

(c) Un RECLAIMABLE alto significa que el daemon está custodiando en /var/lib/docker capas de imágenes que ningún contenedor referencia. No hacen daño más allá del disco que ocupan, y sirven de caché: si vuelves a usar esa imagen, no hay que descargarla. Se liberan con docker system prune -a, que verás en la lección 01-04.

Solución al ejercicio 3

1. Fallo entre el cliente y el socket/daemon. El cliente no logra siquiera establecer la conversación. Dos causas posibles: el daemon está parado (comprueba con systemctl status docker; en Windows/macOS, que Docker Desktop esté iniciado) o tu contexto apunta a un endpoint que no responde (comprueba docker context ls y echo $DOCKER_HOST). Ojo a la diferencia con permission denied: ese sería un problema de permisos sobre el socket, no de conexión.

2. Fallo entre el daemon y el registro. El mensaje empieza por Error response from daemon, así que el cliente llegó al daemon sin problema; fue el daemon quien no pudo obtener la imagen. Comprobarías: que el nombre y la etiqueta sean correctos, que el repositorio exista, si es privado (entonces falta docker login), y si el registro es interno, que sea alcanzable desde la máquina.

3. Fallo en el daemon, en la fase de configuración de red previa al arranque. El contenedor ni siquiera ha llegado a containerd/runc: el daemon intentó reservar el puerto 8080 del anfitrión y el sistema operativo se lo negó porque ya está ocupado. Comprobarías qué lo ocupa (ss -tlnp | grep 8080, o docker ps por si es otro contenedor tuyo) y, o bien liberas ese puerto, o publicas el contenedor en otro (-p 8081:80).

Docker no es un programa: es un sistema cliente-servidor. El cliente docker solo traduce tus órdenes a llamadas de una API REST que viaja por el socket /var/run/docker.sock —cuyos permisos explican, de un vistazo, tanto el uso de sudo como el hecho de que el grupo docker equivalga a root—. Al otro lado, el daemon dockerd hace el trabajo real y delega hacia abajo en containerd (ciclo de vida y almacenamiento) y runc (creación del proceso aislado según la especificación OCI), una separación en capas que existe para respetar estándares y que permite que el ecosistema no dependa de un único producto.

El daemon custodia cuatro tipos de objeto —imágenes, contenedores, volúmenes y redes— en /var/lib/docker, y usa los registros solo para intercambiar imágenes, no para ejecutarlas. Todo eso está reflejado, literalmente, en la salida de docker info y docker system df, que ahora sabes leer.

Con el mapa mental completo, ya puedes empezar a dar órdenes con criterio. En la siguiente lección, Comandos Básicos de Docker, verás que la CLI está organizada exactamente según esos cuatro objetos (docker <objeto> <acción>), aprenderás los comandos esenciales sobre imágenes, contenedores y sistema, y recorrerás una sesión completa comentada de principio a fin.