Docker
Sintaxis, objetos, inspección, filtros y uso seguro de comandos Docker.
La CLI de Docker no debe aprenderse como una colección de comandos aislados. Funciona mejor si se entiende como una interfaz para consultar y modificar .
La forma moderna suele seguir este patrón:
docker <objeto> <acción> [opciones] [argumentos]Ejemplos:
docker container ls
docker image inspect node:22
docker volume create app-data
docker network connect backend api
docker context use productionTambién existen aliases históricos como docker ps, docker rm o docker images. Son válidos, pero el formato objeto-acción ayuda a construir un modelo mental consistente.
Docker administra múltiples clases de recursos:
Sin una organización clara, es fácil ejecutar un comando destructivo sobre el objeto equivocado, confundir configuración con estado o depender de copiar comandos sin entender sus efectos.
La CLI permite:
Cada recurso tiene una identidad y propiedades. Un container, por ejemplo, combina:
identidad
+ image
+ configuración de runtime
+ relaciones con network y mounts
+ estado observadoLa CLI no siempre muestra todo en una tabla. docker container ls presenta un resumen; docker inspect devuelve la configuración efectiva y estado detallado.
Por eso el flujo normal de diagnóstico es:
listar
→ seleccionar un recurso
→ inspeccionar
→ observar logs/eventos/recursos
→ actuarAntes de memorizar flags, usa la ayuda jerárquica:
docker --help
docker container --help
docker container run --help
docker compose --helpLa ayuda de la versión instalada es importante porque opciones y comportamientos evolucionan. Un tutorial antiguo puede usar flags deprecados o asumir una versión diferente.
También comprueba versiones:
docker version
docker compose version
docker buildx versionNo asumas que Docker Engine, Compose y Buildx tienen el mismo ciclo de versión.
docker container ls
docker container ls --all
docker container ls --filter status=exitedSin --all, solo aparecen running containers. Un proceso que sale inmediatamente puede parecer “desaparecido” si usas únicamente docker ps.
docker container create --name api my-api:1.0
docker container start apidocker run combina pull implícito cuando hace falta, create y start:
docker container run --name api my-api:1.0Esto es conveniente, pero entender las operaciones separadas ayuda a distinguir configuración de arranque.
docker container stop api
docker container kill apistop intenta una terminación ordenada mediante señal y timeout. kill envía una señal inmediata, SIGKILL por defecto. Usar kill como primera reacción puede impedir flush de datos y borrar evidencia del shutdown.
docker container rm api
docker container rm --force apiEliminar un container borra su writable layer, pero no necesariamente named volumes o images. Debes conocer la relación entre objetos antes de limpiar.
docker inspect apiEl resultado JSON incluye:
Puedes extraer campos:
docker inspect --format '{{.State.Status}}' api
docker inspect --format '{{.State.ExitCode}}' api
docker inspect --format '{{json .Mounts}}' api
docker inspect --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' apiLos templates Go son útiles para humanos y scripts pequeños, pero para automatización compleja puede ser más seguro consumir JSON con una herramienta estructurada como jq.
docker inspect api | jq '.[0].State'docker logs api
docker logs --follow --since 10m --tail 200 apidocker logs solo muestra lo capturado por el logging driver desde stdout/stderr. No puede recuperar automáticamente archivos internos que la aplicación escribió en otro path.
docker top apiPermite ver procesos desde la perspectiva del host sin depender de que la image incluya ps.
docker exec -it api shexec crea un proceso adicional dentro de namespaces del container. No reemplaza el proceso principal y termina si el container se detiene.
No todas las images contienen shell. Distroless puede no tener sh, bash, curl ni package manager. Diseña diagnóstico mediante logs, métricas y debug containers, no instalando herramientas dentro de producción.
Mantiene stdin abierto.
Asigna una pseudo-TTY.
Ejecuta detached y devuelve el control a la terminal.
docker run -it --rm alpine sh
docker run -d --name api my-apiUn TTY puede modificar buffering y formato de salida. En scripts de CI normalmente no necesitas -t.
docker image ls
docker image pull node:22-slim
docker image inspect node:22-slim
docker image history node:22-slim
docker image rm node:22-slimDistingue:
Eliminar un tag no siempre elimina todo el contenido si otra referencia o container lo necesita.
docker network ls
docker network inspect app-net
docker network create app-net
docker network connect app-net api
docker network disconnect app-net apiinspect permite ver containers conectados, subnets, gateway, aliases y opciones del driver.
No uses la IP interna como configuración estable. Los nombres DNS en user-defined networks son la abstracción esperada.
docker volume ls
docker volume inspect db-data
docker volume create db-data
docker volume rm db-dataUn volume sin container conectado puede seguir conteniendo datos importantes. “Unused” significa no referenciado actualmente, no “seguro para borrar”.
Los filtros evitan parsear tablas visuales:
docker ps --filter status=exited
docker ps --filter label=com.example.project=wiki
docker image ls --filter dangling=true
docker volume ls --filter label=environment=developmentLas labels son especialmente útiles para ownership, proyecto, ambiente y políticas de limpieza.
docker run -d \
--label com.example.project=wiki \
--label com.example.owner=nicolas \
my-apiLas tablas por defecto están hechas para personas y pueden cambiar. Usa --format:
docker ps --format '{{.ID}}\t{{.Names}}\t{{.Status}}'Para JSON cuando esté disponible:
docker ps --format jsonEn scripts, evita:
docker ps | grep apiPuede coincidir con image, command o otro nombre. Prefiere:
docker ps --filter name='^/api$' --quietAun así, diseña manejo de cero, uno o varios resultados.
La CLI devuelve un exit code que un script debe comprobar.
docker inspect missing-container
echo $?No confíes únicamente en texto de salida. Con pipelines de shell, usa opciones como set -euo pipefail conscientemente y captura errores cuando necesites limpieza.
Ejemplo:
set -euo pipefail
container_id=$(docker run -d my-api:test)
trap 'docker rm -f "$container_id" >/dev/null 2>&1 || true' EXIT
docker logs "$container_id"docker context ls
docker context show
docker --context staging psLa misma orden puede actuar sobre un laptop, staging o producción. Antes de acciones destructivas:
expected=staging
actual=$(docker context show)
if [ "$actual" != "$expected" ]; then
echo "Contexto inesperado: $actual" >&2
exit 1
fiNo dependas solo del color del prompt o memoria del operador.
docker events
docker events --since 30m --filter type=containerLos eventos muestran create, start, die, restart, destroy, pull y otras transiciones. Son útiles para reconstruir qué ocurrió cuando un container reinicia rápidamente.
Limitaciones:
docker stats
docker stats --no-stream
docker system df -vdocker stats muestra consumo observado, pero debes interpretar cgroups, cache y límites. system df ayuda a distinguir images, containers, volumes y build cache.
Comandos como:
docker container prune
docker image prune
docker builder prune
docker system pruneeliminan categorías de recursos no usados según Docker. Antes de ejecutarlos:
docker system prune --all --volumes puede eliminar imágenes útiles para rollback y volumes no conectados con datos valiosos.
docker ps --all --filter name='^/api$'
docker inspect api --format '{{json .State}}' | jq
docker logs --tail 200 api
docker events --since 10m --filter container=api
docker stats --no-stream apiFlujo:
ps -a confirma que existe y muestra reinicios.inspect revela exit code, OOM y health.logs muestra error de aplicación.events confirma la secuencia temporal.stats ayuda si aún está running.Si OOMKilled es true, aumentar memoria puede estabilizar temporalmente, pero debes analizar heap, concurrencia y límites. Si el exit code es 127, revisa command y archivos. Si health falla, distingue healthcheck defectuoso de aplicación no disponible.
name=api puede coincidir con api, api-worker y old-api. Usa anchors cuando corresponda.
docker exec -it api sh falla aunque la aplicación esté bien. La image puede ser distroless.
La app puede escribir a archivos, usar otro logging driver o fallar antes de emitir salida.
Al salir desaparece su metadata. Usa logs centralizados o ejecuta sin --rm durante diagnóstico controlado.
docker cp, bind mounts y paths se relacionan con el host remoto según la operación. No asumas filesystem local.
Scripts que parsean columnas visuales son frágiles. Usa JSON, filtros y formatos explícitos.
Son difíciles de revisar y reproducir. Cuando la configuración deja de ser experimental, muévela a Compose o infraestructura como código.
El cambio desaparece al recrear y rompe trazabilidad. Corrige source o Dockerfile y despliega una nueva image.
Antes de borrar, inspecciona nombre, labels, mounts y ambiente.
Puede producir falsos positivos o romperse con cambios de formato.
Primero mide qué consume espacio y protege datos.
Que docker start devuelva éxito significa que el runtime inició el proceso, no que la aplicación esté ready.
No conviertas un script de shell con cientos de llamadas CLI en un orquestador accidental.
docker run -d \
--name cli-lab \
--label purpose=learning \
--memory 64m \
alpine sleep 300
docker ps --filter label=purpose=learning
docker inspect cli-lab --format '{{json .HostConfig.Memory}}'
docker top cli-lab
docker exec cli-lab ps
docker events --since 5m --filter container=cli-lab
docker rm -f cli-labObserva cómo cada comando consulta una dimensión diferente: inventario, configuración, procesos, ejecución adicional, eventos y lifecycle.
exec sirve para diagnóstico, no para hacer cambios persistentes.docker start exitoso no demuestra readiness?docker exec y el proceso principal?prune?Imágenes, layers y content addressing, para comprender qué artefacto manipulan pull, build, inspect y run.