Llevas tres lecciones construyendo. Cada docker build de las anteriores ha dejado capas en tu disco, y a estas alturas tu máquina acumula auroralibros/aurora-api en varias versiones, las bases node, postgres, redis, nginx y alpine, las imágenes de laboratorio de los ejercicios y una caché de BuildKit que no has mirado nunca. Esta lección trata de administrar ese almacén: saber qué tienes, por qué ocupa lo que ocupa, cómo auditar de qué está hecha una imagen, cómo borrar sin llevarte por delante lo que necesitas, de dónde salen esas misteriosas imágenes <none>:<none> que aparecen build tras build, y cómo llevarte una imagen a otra máquina cuando no hay ningún registro por medio. Es la lección menos vistosa del módulo y la que más disgustos te va a evitar: un docker system prune -a --volumes mal entendido borra en diez segundos datos que costaron semanas.

1. Listar imágenes: docker image ls y sus opciones
2. Inspeccionar: docker image inspect y --format
3. Auditar cómo se hizo: docker image history
4. Borrar imágenes: docker image rm
5. Imágenes dangling: las <none>:<none>
6. Limpieza con la familia prune
7. Diagnóstico del espacio: docker system df
8. Portar imágenes sin registro: save/load y export/import
9. Rutina de mantenimiento recomendada

El punto de partida, con la gramática docker <objeto> <acción> de la lección 01-04:

docker images es el alias corto y hace exactamente lo mismo.

Un aviso fundamental sobre la columna SIZE, que ya intuiste en la lección 01-05: los tamaños no se suman. Las tres versiones de aurora-api dicen 167 MB cada una, pero no ocupan 501 MB en disco. Comparten la base node:22-alpine y buena parte de sus capas; el espacio real lo dirá docker system df en el apartado 7.

El digest sale <none> porque estas imágenes se construyeron en local y nunca se han publicado: el digest del manifiesto lo asigna el registro al recibir el push. En cuanto las publiques en la lección 02-06, esa columna se rellenará.

Solo aparece la 1.1.0, porque es la única que lleva las etiquetas OCI. Aquí se ve el rendimiento práctico del trabajo de la lección anterior: los metadatos no eran decoración, son un índice consultable.

Recuperando --format de la lección 01-04:

Campos disponibles: .ID, .Repository, .Tag, .Digest, .CreatedSince, .CreatedAt, .Size.

Sin la palabra table, la salida es texto plano, perfecto para scripts:

Y en JSON, para procesar con jq:

docker image inspect vuelca todos los metadatos de una imagen en JSON. Sin filtro son cientos de líneas:

La gracia está en extraer solo lo que necesitas. La sintaxis de --format es la misma de la lección 01-04, y estos son los campos que más vas a usar:

Este es el comando con el que auditas que no hay ningún secreto dentro de una imagen antes de publicarla. Conviértelo en un reflejo.

Si esto dijera linux/amd64 y estuvieras en un Mac con Apple Silicon, la imagen funcionaría por emulación, mucho más lenta. Es la primera comprobación ante un contenedor inexplicablemente lento.

Un comando, y ya sabes exactamente qué commit lleva dentro esa imagen.

Puedes inspeccionar varias a la vez y comparar:

Ahí se ve la genealogía completa: Alpine aporta 1 capa, Node añade 3 más, y tu Dockerfile las 3 restantes (los dos COPY y el RUN).

docker image history reconstruye la historia de construcción de una imagen capa a capa. Es la herramienta de auditoría por excelencia y ya la usaste en la lección 02-01 para evaluar imágenes ajenas.

Cómo leerlo:

• Se lee de abajo arriba. La última línea es la primera capa (el sistema de archivos base de Alpine); la primera línea es la instrucción más reciente.
• <missing> no es un error. Solo la capa superior tiene un ID propio; las intermedias de una imagen construida con BuildKit no lo exponen. Es normal.
• La columna SIZE es la que importa. Ahí se ve que el RUN npm ci aporta 24,7 MB y los dos COPY apenas 52 kB y 44 kB juntos. Todos los metadatos —ENV, EXPOSE, USER, LABEL, HEALTHCHECK, ENTRYPOINT, CMD— pesan 0 B, exactamente como se anunció en la lección anterior.
• La historia incluye la de la imagen base. Las líneas de "6 días" son de node:22-alpine: ves cómo la construyeron sus mantenedores.

Es el uso más rentable del comando:

Cuando una imagen pesa 900 MB y no sabes por qué, este comando te da la respuesta en un segundo. Los sospechosos habituales: cachés de gestores de paquetes sin limpiar, herramientas de compilación que se quedaron dentro y ficheros temporales borrados en otra capa (con el efecto nulo que demostraste en la lección 02-03).

Por defecto la columna CREATED BY se corta. Para auditar de verdad, hace falta el texto entero:

Este es el comando con el que detectas en una imagen ajena un curl … | sh sospechoso, la instalación de una herramienta que no esperabas o, en tu propia imagen antes de publicarla, un --build-arg con una contraseña como el de la lección 02-04.

Una limitación honesta: history muestra las instrucciones, no el contenido. Un fichero copiado con COPY no se ve aquí. Para eso, arrancar la imagen y mirar (docker run --rm imagen ls -la /app) o herramientas de terceros como dive (lección 07-04).

docker rmi es el alias corto. Fíjate en la salida: Untagged y Deleted son dos cosas distintas, y entender la diferencia es la clave de todo este apartado.

Cuando dos etiquetas apuntan a la misma imagen (el mismo IMAGE ID), borrar una no borra la imagen:

Mismo IMAGE ID: es una imagen con dos nombres, no dos imágenes de 167 MB. Ahora borra una:

Solo Untagged, sin ningún Deleted. Se ha quitado el nombre; los datos siguen ahí porque 1.1.0 los sigue referenciando. El Deleted solo aparece cuando desaparece la última referencia. Esta es la razón de que a veces borres una imagen y no recuperes ni un byte de disco.

Borrar por ID cuando hay varias etiquetas apuntando a esa imagen falla:

Docker se niega porque no sabe qué nombre quieres eliminar. O borras cada etiqueta por su nombre, o usas -f para eliminarlas todas de golpe.

El más frecuente de todos:

El contenedor está parado, no en ejecución, y aun así bloquea el borrado. Tiene toda la lógica: como aprendiste en la lección 01-05, un contenedor parado conserva su capa de escritura, que se apila encima de las capas de la imagen. Borrar la imagen dejaría esa capa flotando sobre la nada, y el contenedor no podría volver a arrancar.

Las tres salidas posibles:

¿Cuándo es aceptable -f? Menos veces de las que se usa:

El peligro de -f sobre un contenedor en ejecución: la imagen queda "borrada" del listado pero sus capas siguen ocupando disco mientras el contenedor viva, y el contenedor no podrá reiniciarse cuando se pare. Acabas con un servicio que funciona hasta el primer reinicio y luego es irrecuperable, sin ninguna forma de reconstruirlo salvo el registro. Es un incidente de producción clásico.

El patrón $(docker image ls -q …) combina -q (solo IDs) con la sustitución de comandos del shell. Antes de ejecutar un borrado masivo, ejecuta primero solo la parte interna para ver qué vas a destruir:

Tarde o temprano verás esto:

Esas <none>:<none> son imágenes dangling (colgantes): imágenes reales, completas y perfectamente funcionales, que han perdido su nombre.

La causa principal, con diferencia, es reconstruir con la misma etiqueta:

En la segunda build nace una imagen nueva (contenido distinto, ID distinto) y la etiqueta 1.1.0 se mueve a ella. La imagen A no se borra: se queda sin nombre. Es exactamente el modelo de la lección 02-01 —las etiquetas son punteros móviles a digests inmutables—, visto desde el lado local.

Compruébalo:

Las otras dos fuentes:

• Builds sin -t. docker build . produce una imagen sin nombre desde el primer segundo. Es el motivo del consejo de la lección 02-02: etiqueta siempre.
• Builds fallidas que dejaron capas intermedias.

Porque se acumulan en silencio. Un desarrollador que reconstruye veinte veces al día con la misma etiqueta genera veinte imágenes dangling diarias. La mayoría comparten capas y no ocupan 167 MB cada una, pero las capas propias (el COPY . . y a veces el RUN npm ci) sí son exclusivas. En unas semanas son varios gigabytes, y el mensaje no space left on device llega en el peor momento.

No son basura absoluta: si sabes su ID, puedes ejecutarlas y hasta reetiquetarlas.

Eso salva la papeleta cuando borras por error la etiqueta de una imagen que aún no habías publicado. Pero como práctica habitual, se limpian.

Cuatro comandos, con cuatro radios de destrucción muy distintos. Esta tabla es la que hay que memorizar:

Este es el que puedes ejecutar con confianza: solo se lleva imágenes sin nombre. Con -f se salta la confirmación (útil en scripts) y con --filter "until=168h" limita el borrado a las de más de una semana:

Lee bien el aviso: borra todas las imágenes que no tengan un contenedor asociado, no solo las dangling. Si no tienes contenedores creados —lo normal después de limpiar—, esto se lleva node:22-alpine, postgres:16-alpine, redis:7-alpine, tus aurora-api locales y todo lo demás. No es catastrófico (se puede reconstruir y redescargar), pero significa gigabytes de descarga y, si estás sin conexión o cerca del límite de descargas de la lección 02-01, un mal rato.

La caché de BuildKit es invisible en docker image ls y suele ser lo más voluminoso de la máquina:

Casi tres gigas que no aparecían en ningún listado de imágenes. Variantes:

La contrapartida: la siguiente build de cada proyecto irá en frío. Recuerda de la lección 02-02 que ahí es donde la caché no ayuda.

El aviso lista exactamente lo que va a borrar. Léelo siempre: es la diferencia entre limpiar y perder trabajo. Lo que se lleva por sorpresa suele ser un contenedor parado que contenía datos en su capa de escritura, o una red que habías creado a mano para unas pruebas.

Esta es la línea que arruina el día: all volumes not used by at least one container.

Traducido a Aurora Libros: cuando en el módulo 3 tengas un volumen con el catálogo de PostgreSQL y hayas parado y borrado el contenedor de aurora-db para recrearlo, ese volumen queda temporalmente sin contenedor asociado. Un docker system prune -a --volumes en ese momento borra la base de datos entera. Sin papelera, sin deshacer, sin recuperación.

Reglas de uso:

• Nunca en un servidor. Nunca.
• En desarrollo, solo cuando tengas claro que no hay ningún volumen que te importe.
• Antes de ejecutarlo, mira qué volúmenes hay:

• Si solo quieres espacio, la escalera segura es: docker image prune → docker builder prune → docker system prune. Rara vez hace falta llegar al último escalón.

Antes de borrar nada, mide.

Cómo leerlo:

Dos conclusiones inmediatas de este ejemplo:

1. Nueve imágenes ocupan 842 MB, no la suma de sus columnas SIZE en docker image ls (que daría más de 1,2 GB). La diferencia son las capas compartidas de la lección 01-05, contadas una sola vez.
2. La caché de build es 2,85 GB, el 100 % recuperable, y es con diferencia lo más grande. Es lo primero que hay que limpiar, y no aparecía en ningún listado de imágenes.

Las columnas SHARED SIZE y UNIQUE SIZE son las que aclaran todo:

• node:22-alpine: 142 MB de tamaño, 142 MB compartidos, 0 B únicos. Borrarla no liberaría nada, porque todas sus capas las usan tus imágenes de aurora-api.
• aurora-api:1.0.0: 167 MB, de los cuales solo 24,7 MB son exclusivos. Eso es lo que ganarías al borrarla.
• postgres:16-alpine: 278 MB con 270 MB únicos. Esta sí es un buen candidato si no la vas a usar.

Y mira la última línea de volúmenes: f3a9c2e1b8d7… con 0 links es un volumen anónimo huérfano, exactamente lo que anticipaba la lección 02-04 al desaconsejar VOLUME en el Dockerfile. Ocupa 61,7 MB y nadie sabe qué contiene.

A veces hay que llevar una imagen a otra máquina sin registro por medio: un cliente con la red aislada, un entorno sin salida a Internet, una demo en un portátil sin conexión. Docker ofrece dos parejas de comandos que se confunden constantemente y que no son intercambiables.

La regla: para mover una imagen, siempre save/load. export/import sirve para otra cosa.

De 168 MB a 62 MB: un 63 % menos, y eso es lo que viaja por el pendrive o el SCP. También se puede hacer en un solo paso con una tubería:

Mismo IMAGE ID, mismo ENTRYPOINT, mismo USER. La imagen ha llegado íntegra, con todos los metadatos que definiste en la lección 02-04.

Guardar varias imágenes en un solo fichero, útil para llevarse la pila entera de Aurora Libros:

Un único fichero con todo lo necesario para levantar la plataforma en una máquina sin Internet.

Trabaja sobre contenedores, no imágenes, y aplana el resultado:

Una sola capa y ningún historial. Toda la genealogía ha desaparecido. Y lo grave:

Se han perdido el ENTRYPOINT, el CMD, el ENV, el USER y el EXPOSE. La imagen importada es un sistema de archivos sin instrucciones. Habría que reponerlos a mano al ejecutar:

Entonces, ¿para qué sirve? Para dos cosas legítimas:

1. Aplanar una imagen con demasiadas capas o con un secreto enterrado en una capa intermedia que quieres eliminar de verdad. Al aplanar, esa capa desaparece. (La forma moderna y mejor de conseguirlo son las builds multi-etapa, lección 05-04.)
2. Extraer el sistema de archivos de un contenedor para analizarlo forensemente o para construir una imagen base a partir de un sistema existente.

Se pueden reponer los metadatos al importar, con -c:

Funciona, pero has tenido que reconstruir a mano lo que save conservaba solo. Queda claro cuál es la herramienta adecuada para portar imágenes.

Limpieza:

Con todo lo anterior, esta es una rutina razonable para una máquina de desarrollo.

Semanal (seguro, se puede automatizar):

Borra las dangling y la caché de build de más de una semana, y muestra cómo queda el espacio. No toca nada con nombre, ni contenedores, ni volúmenes.

Mensual (revisión manual):

Aquí no se automatiza nada: se mira y se decide. Los volúmenes huérfanos hay que inspeccionarlos antes de borrarlos, porque pueden contener datos.

Antes de una build importante:

Caché limpia y base actualizada, como se explicó en la lección 02-02.

Cuando falta espacio, la escalera segura:

En cinco pasos ordenados de menor a mayor riesgo se recuperan casi siempre varios gigabytes sin llegar nunca a docker system prune -a --volumes.

Un script de mantenimiento con informe:

Fíjate en la última sección: lista los volúmenes huérfanos pero no los borra. Esa es la línea que separa un script de mantenimiento de un script de destrucción de datos.

• Sumar la columna SIZE de docker image ls. No es espacio en disco: las capas compartidas se cuentan en cada fila. El dato real está en docker system df, y el desglose en docker system df -v.
• Borrar una etiqueta y esperar recuperar espacio. Si la salida solo dice Untagged y no Deleted, no has liberado nada: la imagen tiene otra referencia.
• docker image rm -f sobre un contenedor en ejecución. La imagen "desaparece" pero sus capas siguen en disco y el contenedor no podrá reiniciarse nunca más. Para el contenedor primero.
• docker system prune -a --volumes sin leer el aviso. Borra volúmenes sin contenedor asociado, y un volumen de base de datos entre recreaciones de contenedor está exactamente en ese estado. Nunca en un servidor.
• Ignorar la caché de BuildKit. No aparece en docker image ls y suele ser lo más voluminoso de la máquina. docker system df la delata.
• Confundir save/load con export/import. export pierde ENTRYPOINT, CMD, ENV, USER y el historial, y la imagen importada da no command specified. Para portar imágenes, siempre save/load.
• Olvidar comprimir el .tar. Un gzip -9 recorta habitualmente entre un 50 % y un 65 %.
• Consejo: audita las variables antes de publicar. docker image inspect --format '{{range .Config.Env}}{{println .}}{{end}}' debe ser un reflejo antes de cualquier docker push.
• Consejo: usa docker image history … | sort -rh para cazar capas gordas. Es el diagnóstico de "por qué pesa tanto esta imagen" en un solo comando.
• Consejo: etiqueta siempre con -t. Cada build sin etiqueta es una imagen dangling desde el primer segundo.
• Consejo: antes de un borrado masivo, ejecuta solo la parte interna del $( … ) para ver qué vas a destruir.

1. Ejecuta docker system df y anota el total y el porcentaje recuperable de cada categoría.
2. Con docker system df -v, identifica la imagen con mayor UNIQUE SIZE y la que tenga UNIQUE SIZE de 0 B. Explica qué significa cada caso y cuánto liberaría borrar cada una.
3. Localiza con docker image history la capa más pesada de auroralibros/aurora-api:1.1.0 y de postgres:16-alpine.
4. Comprueba si tienes volúmenes huérfanos y averigua, sin borrarlos, de qué imagen salieron.

1. Construye auroralibros/aurora-api:experimento desde tu Dockerfile y anota el IMAGE ID.
2. Crea una segunda etiqueta auroralibros/aurora-api:copia apuntando a la misma imagen. Comprueba que el ID coincide y que docker system df no ha crecido.
3. Borra la etiqueta copia. ¿Sale Untagged, Deleted o ambos? ¿Por qué?
4. Modifica server.js, reconstruye con la misma etiqueta experimento y comprueba que aparece una imagen <none>:<none>. Explica de dónde salió.
5. Recupera esa imagen dangling reetiquetándola como auroralibros/aurora-api:rescatada y verifica que funciona.
6. Limpia todo lo creado en el ejercicio.

Simula un despliegue en un entorno aislado:

1. Exporta en un único fichero auroralibros/aurora-api:1.1.0, postgres:16-alpine y redis:7-alpine.
2. Comprímelo y anota el tamaño antes y después.
3. Borra las tres imágenes de tu máquina (simulando la máquina destino en blanco).
4. Cárgalas desde el fichero y verifica que aurora-api conserva ENTRYPOINT, USER, ENV y el HEALTHCHECK.
5. Repite el ciclo con export/import sobre un contenedor de aurora-api y compara: tamaño del tar, número de capas del history y comportamiento al ejecutar docker run sin argumentos. Concluye qué pareja usarías y por qué.

Solución al ejercicio 1

1. Total aproximado: 3,95 GB, de los cuales 3,65 GB son recuperables. La caché de build es el 72 % de todo y es 100 % recuperable: es el objetivo prioritario.

2.

• Mayor UNIQUE SIZE: postgres:16-alpine, con 270 MB únicos de sus 278 MB. Solo comparte con las demás la capa base de Alpine (8,17 MB). Borrarla liberaría 270 MB reales.
• UNIQUE SIZE de 0 B: node:22-alpine. Sus 142 MB están íntegramente compartidos con tus imágenes de aurora-api, que se construyeron sobre ella. Borrarla no liberaría ni un byte mientras exista alguna imagen derivada; solo desaparecería del listado. Es la demostración práctica de las capas compartidas de la lección 01-05.

3.

En aurora-api, el npm ci con 24,7 MB es el mayor contribuyente propio: son las dependencias de producción. En postgres, los 248 MB de la compilación de PostgreSQL explican por sí solos su tamaño.

4.

El contenido delata su origen: es un volumen anónimo creado por la imagen de PostgreSQL, que declara VOLUME /var/lib/postgresql/data en su Dockerfile. Es exactamente el escenario que la lección 02-04 daba como razón para no usar VOLUME. No lo borres sin comprobar el contenido: podría ser una base de datos con trabajo dentro.

Solución al ejercicio 2

Mismo ID y el mismo espacio total. docker image tag solo crea una referencia; no copia un solo byte. Es la demostración local de lo que verás en el registro en la lección 02-06.

Solo Untagged. No hay Deleted porque la etiqueta experimento sigue apuntando a esa imagen: los datos siguen referenciados y el borrado se limita a eliminar el nombre.

El ID 4e9c7d2a8f31 es el mismo del paso 1: la imagen original no se ha borrado, ha perdido el nombre. La nueva build produjo una imagen distinta y la etiqueta experimento se movió a ella. Las etiquetas son punteros, no propietarios.

Recuperada y funcional, y ya no figura como dangling porque vuelve a tener nombre. Fíjate en que --version funcionó gracias al ENTRYPOINT ["node"] de la lección 02-04.

Solución al ejercicio 3

De 481 MB a 173 MB: un 64 % menos. La compresión merece la pena siempre, sobre todo si el fichero viaja por SCP o por un pendrive.

Absolutamente todo intacto: entrypoint, cmd, usuario, variables, healthcheck y hasta las etiquetas OCI con el hash del commit.

Tabla comparativa final:

Conclusión: para portar imágenes, save/load, sin discusión. El pequeño ahorro de tamaño de export no compensa perder toda la configuración de ejecución, el healthcheck y la trazabilidad que costó una lección entera construir. export/import es una herramienta para aplanar sistemas de archivos, no para mover imágenes.

Limpieza:

Ya sabes administrar tu almacén de imágenes. Listas y filtras con docker image ls, sus --filter (incluido el filtrado por las etiquetas OCI que añadiste en 02-04) y sus plantillas Go. Extraes cualquier metadato concreto con docker image inspect --format, y tienes un reflejo nuevo que conviene conservar: auditar las variables de entorno antes de publicar cualquier imagen. Con docker image history reconstruyes cómo se hizo una imagen, capa a capa, y localizas en un solo comando la que se comió los megas —en aurora-api, el npm ci con 24,7 MB; en postgres, los 248 MB de su compilación—.

Sabes borrar entendiendo lo que pasa: Untagged quita un nombre y Deleted destruye datos, y solo aparece cuando cae la última referencia. Sabes por qué un contenedor parado bloquea el borrado de su imagen (conserva la capa de escritura apilada encima) y cuándo -f es aceptable y cuándo es una forma elegante de romper un servicio en el próximo reinicio. Entiendes de dónde salen las <none>:<none>: reconstruir con la misma etiqueta mueve el puntero y deja huérfana a la imagen anterior, que sigue en disco y hasta se puede rescatar reetiquetándola.

Dominas la escalera de limpieza, de menor a mayor riesgo —image prune, builder prune, system prune— con una advertencia grabada a fuego sobre el último escalón: docker system prune -a --volumes borra volúmenes sin contenedor asociado, y un volumen de base de datos entre recreaciones está exactamente en ese estado. Mides antes de tocar nada con docker system df y su versión -v, que revela lo que ningún listado de imágenes muestra: la caché de BuildKit ocupando gigabytes, las capas compartidas contadas una sola vez y las columnas SHARED/UNIQUE que dicen cuánto liberarías de verdad al borrar cada imagen. Y sabes llevarte una imagen a una máquina aislada con docker save/load, conservando entrypoint, usuario, healthcheck y etiquetas OCI, frente a export/import, que aplana el sistema de archivos y lo pierde todo.

Tu imagen está construida, es profesional y sabes mantenerla. Le falta lo único que justificaba todo el módulo: salir de tu máquina. En la última lección, Etiquetado y Publicación de Imágenes, cerrarás el ciclo. Verás que docker image tag no copia nada sino que crea referencias, decidirás una estrategia de etiquetado seria —versionado semántico con etiquetas móviles y fijas, por SHA de commit, por rama, por entorno— y publicarás auroralibros/aurora-api en Docker Hub y en GitHub Container Registry, leyendo la salida del push, verificando el resultado con docker manifest inspect y entendiendo por qué en producción se despliega por digest y jamás por latest.