Primeros pasos
Comandos básicos
docker run crea e inicia un contenedor. -d ejecuta en segundo plano, -p mapea el puerto del host al del contenedor. pull descarga imágenes de un registro (Docker Hub por defecto).
# check version
docker --version
# pull an image
docker pull nginx:latest
# run a container
docker run -d --name mynginx -p 8080:80 nginx
# list running containers
docker ps
# list all containers (including stopped)
docker ps -a
# stop and remove a container
docker stop mynginx
docker rm mynginx
# list images
docker imagesCiclo de vida del contenedor
create + start es lo que run hace por debajo. stop envía SIGTERM para un apagado elegante; kill envía SIGKILL de inmediato. pause usa el congelador de cgroups — útil para instantáneas sin detener el proceso.
# create a container without starting it
docker create --name web nginx
# start a created (or stopped) container
docker start web
# stop gracefully (SIGTERM then SIGKILL after 10s)
docker stop web
# force kill immediately
docker kill web
# restart a container
docker restart web
# pause/resume (freezes process with cgroups)
docker pause web
docker unpause webFundamentos de imágenes
Las imágenes son capas de solo lectura. rmi falla si un contenedor aún referencia la imagen — elimina primero el contenedor. history muestra cada instrucción que creó una capa y su tamaño, útil para optimizar builds.
# list local images
docker images
docker image ls
# remove an image
docker rmi nginx:latest
docker image rm nginx
# remove all dangling (untagged) images
docker image prune
# remove all unused images
docker image prune -a
# show image history (each layer)
docker history nginx:latestInformación del sistema
docker info muestra la configuración del daemon: driver de almacenamiento, runtime, registros, estado de swarm. system df revela el espacio recuperable — imágenes colgantes y contenedores detenidos desperdician disco. El flag --format usa plantillas de Go para salida estructurada.
# docker system-wide info
docker info
docker version
# disk usage breakdown (images, containers, volumes)
docker system df
# detailed disk usage with reclaimable space
docker system df -v
# running containers count
docker ps -q | wc -l
# show docker root directory and storage driver
docker info --format '{{.DockerRootDir}} {{.Driver}}'Limpieza y prune
prune elimina de forma segura recursos detenidos/colgantes. system prune -a también elimina imágenes no referenciadas por ningún contenedor. Añadir --volumes borra volúmenes no usados por ningún contenedor — pérdida de datos irreversible, úsalo con cuidado en producción.
# remove stopped containers
docker container prune
# remove dangling images
docker image prune
# remove unused volumes (CAUTION: data loss)
docker volume prune
# remove unused networks
docker network prune
# remove everything unused at once
docker system prune
# also remove volumes (very aggressive)
docker system prune -a --volumesObtener ayuda
Docker agrupa los comandos en espacios de nombres de gestión (docker image, docker container, docker network, docker volume). Tanto la forma antigua (docker rmi) como la nueva (docker image rm) funcionan. --help en cualquier subcomando muestra los flags y el uso.
# list all commands
docker --help
docker help
# help for a specific command
docker run --help
docker image --help
# list management commands (grouped)
docker image --help
docker container --help
docker network --help
# show daemon config
docker info
# command reference online
# https://docs.docker.com/reference/Gestión de imágenes
Descargar imágenes
Los tags son etiquetas mutables — el mismo tag puede apuntar a imágenes distintas con el tiempo. Para despliegues reproducibles, fija por digest (@sha256:...). Descargar con --platform permite obtener una imagen para otra arquitectura, útil para builds ARM en hosts x86.
# pull latest tag
docker pull nginx
# pull specific tag
docker pull nginx:1.25-alpine
# pull all tags of a repository
docker pull -a alpine
# pull from a different registry
docker pull ghcr.io/user/repo:tag
# pull by digest (immutable, reproducible)
docker pull nginx@sha256:abc123...
# pull multiple platforms (multi-arch)
docker pull --platform linux/arm64 nginxConstruir imágenes
El . final es el contexto de build — los archivos que se envían al daemon. Mantenlo pequeño con .dockerignore para acelerar los builds. --no-cache fuerza capas nuevas al depurar. BuildKit habilita caché multi-etapa, montajes SSH y montaje de secretos.
# build from Dockerfile in current dir, tag it
docker build -t myapp:1.0 .
# build with a different Dockerfile name
docker build -f Dockerfile.prod -t myapp:prod .
# build with build args
docker build --build-arg VERSION=1.2.3 -t myapp .
# build with no cache
docker build --no-cache -t myapp .
# build for a different platform
docker build --platform linux/arm64 -t myapp:arm .
# build using BuildKit (advanced features)
DOCKER_BUILDKIT=1 docker build -t myapp .Etiquetar imágenes
Los tags son alias que apuntan al mismo ID de imagen. Un flujo de trabajo común construye con un tag de versión y luego añade los tags latest y de versión mayor. Etiquetar con la URL de un registro prepara la imagen para un push a ese registro.
# tag a local image
docker tag myapp:1.0 myapp:latest
# tag for pushing to Docker Hub
docker tag myapp:1.0 username/myapp:1.0
# tag for a private registry
docker tag myapp:1.0 registry.local:5000/myapp:1.0
# tag with multiple tags at once
docker tag myapp:1.0 myapp:stable
docker tag myapp:1.0 myapp:1
# tag by digest reference
docker tag myapp@sha256:abc... myapp:pinnedPublicar imágenes
Debes etiquetar la imagen con el destino del registro antes de hacer push. push sube solo las capas que aún no están en el registro. Para registros privados con certificados self-signed, configura el daemon en /etc/docker/daemon.json con insecure-registries.
# login to Docker Hub
docker login
# login to a private registry
docker login registry.local:5000 -u user -p pass
# push to Docker Hub
docker push username/myapp:1.0
# push all tags in a repository
docker push -a username/myapp
# push to private registry
docker push registry.local:5000/myapp:1.0
# logout when done
docker logoutInspeccionar imágenes
inspect devuelve un JSON detallado: arquitectura, SO, capas, env, entrypoint, configuración. history revela el comando y tamaño de cada capa — la base de la optimización de imágenes. manifest inspect consulta un registro remoto sin descargar.
# low-level image metadata (JSON)
docker inspect nginx:latest
# specific field via Go template
docker inspect --format '{{.Arch}} {{.Os}}' nginx
# show image layers and sizes
docker history nginx:latest
# no-trunc to see full command for each layer
docker history --no-trunc nginx:latest
# inspect an image in a registry (manifest)
docker manifest inspect nginx:latestGuardar y cargar imágenes
save/load conserva las capas y el historial de la imagen — la elección correcta para transferir imágenes offline. export/import aplana a una sola capa, perdiendo el historial. Para transferencia en línea, prefiere push/pull de registro antes que archivos tar.
# save an image to a tar file
docker save -o myapp.tar myapp:1.0
# save multiple images
docker save -o bundle.tar myapp:1.0 nginx:latest
# load an image from a tar file
docker load -i myapp.tar
# pipe between hosts (no intermediate file)
docker save myapp:1.0 | gzip | ssh host 'gunzip | docker load'
# export a container filesystem (not an image)
docker export mycontainer | gzip > fs.tar.gzGestión de contenedores
Ejecutar contenedores
-it combina -i (mantener stdin abierto) y -t (asignar una tty) para sesiones interactivas. --rm limpia tras salir — ideal para comandos puntuales. --restart unless-stopped sobrevive a reinicios pero respeta las paradas manuales.
# run in background with a name and port mapping
docker run -d --name web -p 8080:80 nginx
# run interactively with a terminal
docker run -it --name shell alpine sh
# run and auto-remove on exit
docker run --rm alpine echo hello
# run with a volume
docker run -d -v mydata:/data alpine
# run with environment variables
docker run -d -e MYSQL_ROOT_PASSWORD=secret mysql
# run with a restart policy
docker run -d --restart unless-stopped nginxEjecutar comandos (exec)
exec ejecuta un proceso nuevo dentro de un contenedor ya en marcha — el entrypoint original sigue corriendo. Úsalo para depurar, tareas de administración o ejecutar scripts puntuales. El usuario por defecto es el USER de la imagen; sobrescríbelo con -u.
# open an interactive shell in a running container
docker exec -it web sh
# run a command and return
docker exec web ls /usr/share/nginx/html
# run as a specific user
docker exec -u root web whoami
# set environment variables for the command
docker exec -e DEBUG=1 web env
# run with a working directory
docker exec -w /tmp web pwd
# run as detached (rarely useful)
docker exec -d web touch /tmp/markerVer logs
logs muestra el stdout/stderr capturado por el driver de logging del contenedor. Las aplicaciones deberían escribir logs en stdout, no en archivos, para integrarse con docker logs. --since/--until aceptan marcas de tiempo RFC3339 o duraciones de Go (30m, 2h).
# follow (tail) logs
docker logs -f web
# show last 100 lines
docker logs --tail 100 web
# show logs since a timestamp
docker logs --since 2024-01-01T00:00:00 web
# show logs from the last 30 minutes
docker logs --since 30m web
# add timestamps to each line
docker logs -t web
# show logs for a specific timeframe
docker logs --since 10m --until 5m webInspección de contenedores
inspect devuelve un JSON rico que cubre config, estado, red y montajes. Las plantillas de Go extraen campos concretos — extremadamente útil para scripting. El LogPath revela dónde guarda los logs el driver json-file en el host.
# full JSON metadata
docker inspect web
# container IP address
docker inspect --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' web
# container log path (json-file driver)
docker inspect --format '{{.LogPath}}' web
# mounts and volumes
docker inspect --format '{{json .Mounts}}' web
# container state (running, exited, etc.)
docker inspect --format '{{.State.Status}} {{.State.ExitCode}}' web
# all container ports
docker inspect --format '{{json .NetworkSettings.Ports}}' webIniciar, detener y reiniciar
start reanuda un contenedor detenido con su configuración original. update modifica las restricciones y la política de reinicio de un contenedor en marcha sin recrearlo — útil para endurecer los límites de recursos en producción.
# start a stopped container
docker start web
# stop with a custom timeout (seconds)
docker stop -t 30 web
# restart (keeps container intact)
docker restart web
# rename a container
docker rename web webserver
# update container config (e.g. restart policy)
docker update --restart unless-stopped web
# pause/resume (cgroup freezer)
docker pause web
docker unpause webCopiar archivos
cp funciona en ambas direcciones y sobre contenedores detenidos — práctico para inyectar hotfixes o extraer logs. No está diseñado para sincronización de alta frecuencia; usa un bind mount o un volumen para los flujos de desarrollo. El truco tar+exec transmite árboles grandes de forma eficiente.
# copy a file from host to container
docker cp file.txt web:/tmp/
# copy from container to host
docker cp web:/etc/nginx/nginx.conf ./nginx.conf
# copy a directory
docker cp ./app web:/usr/src/app
# copy with archive mode (preserves perms)
docker cp -a ./config web:/etc/app
# copy to a stopped container (works too)
docker cp script.sh web:/script.sh
# tar stream from host to container stdin
docker exec -i web tar xzf - -C /app < app.tar.gzFundamentos del Dockerfile
FROM — imagen base
FROM es la primera instrucción y define la capa base. Elige bases mínimas (alpine, distroless, scratch) para reducir la superficie de ataque y el tamaño. Fijar por digest garantiza builds reproducibles, ya que los tags pueden cambiar.
# use an official base image
FROM ubuntu:22.04
# pin a specific digest for reproducibility
FROM ubuntu@sha256:abc123def...
# multi-arch build (buildx picks the host arch)
FROM --platform=$BUILDPLATFORM golang:1.21 AS builder
# use a minimal image
FROM alpine:3.18
# scratch = empty image, for static binaries
FROM scratch
# use a previous build stage
FROM builder AS finalRUN — ejecutar comandos
Cada RUN crea una capa. Combina comandos relacionados con && y limpia en la misma capa para mantener las imágenes pequeñas. La forma exec (array JSON) no invoca un shell, así que no hay expansión de variables ni encadenamiento — pero maneja las señales correctamente.
# install packages
RUN apt-get update && apt-get install -y curl
# clean up in the same layer to reduce size
RUN apt-get update && apt-get install -y --no-install-recommends curl \
&& rm -rf /var/lib/apt/lists/*
# combine commands with && to reduce layers
RUN mkdir -p /app/config && chown 1000:1000 /app/config
# use exec form (preferred) to ensure signals
RUN ["npm", "install"]
# use a shell for variables and chaining
RUN VERSION=1.0 && wget https://example.com/v${VERSION}.tar.gzCOPY y ADD
COPY es lo preferido para archivos locales — es explícito y predecible. ADD añade magia: descarga de URLs y extracción automática de archivos tar/zip. Esa magia puede sorprenderte; recurre a ADD solo cuando necesites extracción. Ambos crean una capa.
# copy a file into the image
COPY package.json /app/
# copy a directory
COPY src/ /app/src/
# copy with ownership
COPY --chown=node:node package.json /app/
# copy from a previous build stage
COPY --from=builder /app/dist /app/dist
# ADD can fetch URLs and extract archives
ADD https://example.com/app.tar.gz /tmp/
# ADD extracts local tar archives automatically
ADD app.tar.gz /usr/src/WORKDIR
WORKDIR fija el directorio de trabajo para las instrucciones siguientes y el valor por defecto del contenedor. Crea el directorio si falta. Prefiere siempre WORKDIR sobre cd en RUN — cd no persiste entre capas. Usa rutas absolutas por claridad.
# set the working directory
WORKDIR /usr/src/app
# subsequent RUN, CMD, COPY use this dir
COPY . .
RUN npm install
# WORKDIR creates the directory if it does not exist
WORKDIR /opt/data/logs
# use a relative path (relative to previous WORKDIR)
WORKDIR sub
# avoid this anti-pattern (use absolute paths)
WORKDIR /app
RUN cd /app && do_something # cd is lost after RUNUSER
USER fija el usuario (y opcionalmente el grupo) para RUN, CMD y ENTRYPOINT. Ejecutar como non-root es una buena práctica de seguridad clave. El usuario debe existir en la imagen. Los UIDs numéricos son portables entre imágenes y evitan problemas de búsqueda de nombres.
# create a non-root user and switch to it
RUN groupadd -r app && useradd -r -g app appuser
USER appuser
# run subsequent instructions as this user
RUN whoami # appuser
# use a numeric UID for portability
USER 1000
# USER in compose/runtime overrides this
USER 1000:1000
# common pattern: node image ships a 'node' user
FROM node:20-alpine
USER node.dockerignore
.dockerignore reduce el contexto de build enviado al daemon — builds más rápidos, contexto más pequeño y evita que secretos como .env se filtren en las capas de la imagen. Usa una sintaxis similar a .gitignore. Excluye siempre node_modules y los artefactos de build que se regeneran durante la compilación.
# .dockerignore — exclude files from the build context
# version control
.git
.gitignore
# dependencies (fetched inside the image)
node_modules
npm-debug.log
# build artifacts
dist
build
*.log
# local env files (NEVER bake secrets)
.env
.env.local
# docker files themselves
Dockerfile
docker-compose*.yml
# OS files
.DS_Store
Thumbs.dbDockerfile avanzado
CMD vs ENTRYPOINT
ENTRYPOINT define el ejecutable; CMD proporciona los argumentos por defecto que pueden sobrescribirse. Usa la forma exec (array JSON) para que el proceso reciba las señales directamente — la forma shell envuelve el comando en /bin/sh -c, rompiendo el apagado elegante. Un patrón común: script en ENTRYPOINT + argumentos por defecto en CMD.
# CMD: default command, easily overridden
CMD ["nginx", "-g", "daemon off;"]
# override at runtime
# docker run myimage nginx -v
# ENTRYPOINT: fixed command, CMD becomes args
ENTRYPOINT ["nginx"]
CMD ["-g", "daemon off;"]
# runtime args append to ENTRYPOINT
# docker run myimage -v -> nginx -v
# shell form (avoid — no signal handling)
CMD nginx -g "daemon off;"
# script as entrypoint that accepts args
ENTRYPOINT ["./entrypoint.sh"]
CMD ["--help"]ENV — variables de entorno
ENV crea variables a nivel de imagen visibles en build y en ejecución. Usa ARG para valores exclusivos del build y evitar filtrar configuración a la imagen final. En CMD/ENTRYPOINT en forma exec, ${VAR} no se expande por el shell — envuélvelo con sh -c para expandirlo.
# set a persistent env var (baked into image)
ENV NODE_ENV=production
ENV PATH=/app/node_modules/.bin:$PATH
# use in subsequent RUN instructions
ENV VERSION=1.2.3
RUN wget https://example.com/v${VERSION}.tar.gz
# multiple in one line
ENV NODE_ENV=production PORT=3000 LOG_LEVEL=info
# override at runtime
# docker run -e NODE_ENV=development myapp
# view env vars of a container
docker exec web env
# reference env vars in CMD
ENV APP_PORT=3000
CMD ["sh", "-c", "node server.js ${APP_PORT}"]ARG — argumentos de build
Los valores de ARG existen solo durante la build de la etapa que los declara. No persisten en el contenedor en ejecución — usa ENV para llevar un valor al runtime. Los ARG declarados antes de FROM son 'globales' pero deben redeclararse en cada etapa para usarlos ahí.
# declare a build argument with a default
ARG VERSION=latest
FROM base:${VERSION}
# use ARG only during build (not at runtime)
ARG NODE_ENV=production
RUN echo "Building for ${NODE_ENV}"
# multi-stage: ARG must be redeclared per stage
ARG VERSION
FROM base:${VERSION}
ARG VERSION
RUN echo ${VERSION}
# pass at build time
# docker build --build-arg VERSION=1.0 .
# ARG not available in CMD (use ENV to pass through)
ARG PORT=3000
ENV PORT=${PORT}
CMD ["sh", "-c", "serve --port ${PORT}"]EXPOSE
EXPOSE es documentación — no publica puertos. La publicación ocurre con -p (host:contenedor) en ejecución o ports: en Compose. EXPOSE ayuda a las herramientas a entender los puertos previstos y habilita el enlazado automático en redes heredadas.
# document which port the container listens on
EXPOSE 80
# expose multiple ports
EXPOSE 80 443
# expose with protocol
EXPOSE 53/udp
# EXPOSE does NOT publish the port
# you still need -p at runtime
# docker run -p 8080:80 myapp
# in compose, expose vs ports
# expose: only to linked services
# ports: published to the host
# view exposed ports
docker inspect --format '{{json .Config.ExposedPorts}}' myappLABEL y metadatos
LABEL adjunta metadatos clave-valor a las imágenes. Adopta las etiquetas OCI org.opencontainers.image.* por interoperabilidad con registros y herramientas. Las etiquetas son útiles para seguir la versión, la fuente, la licencia y la información de build de CI.
# add a label (key=value metadata)
LABEL maintainer="[email protected]"
LABEL version="1.0"
LABEL description="My web app"
# multiple labels in one instruction
LABEL org.opencontainers.image.title="myapp" \
org.opencontainers.image.version="1.0" \
org.opencontainers.image.source="https://github.com/me/myapp"
# view labels
docker inspect --format '{{json .Config.Labels}}' myapp
# filter images by label
docker images --filter "label=version=1.0"
# deprecated: MAINTAINER (use LABEL maintainer instead)
# MAINTAINER Alice <[email protected]>VOLUME en el Dockerfile
VOLUME declara un punto de montaje; Docker crea un volumen anónimo en la primera ejecución a menos que montes una ruta del host. Señala que el directorio guarda datos con estado. Una trampa: declarar VOLUME después de COPY puede ocultar tus archivos copiados con un volumen vacío.
# declare an anonymous volume mount point
VOLUME /data
# multiple mount points
VOLUME /data /config /logs
# at runtime, Docker creates an anonymous volume
# docker run -v mydata:/data myapp (named instead)
# VOLUME in Dockerfile: any files copied to /data
# are copied into the new anonymous volume on first run
# inspect volumes
docker inspect --format '{{json .Mounts}}' myapp
# avoid: VOLUME after COPY can hide your data
COPY ./config /config
VOLUME /config # new empty volume shadows /configBuilds multi-etapa
Multi-etapa básico
Los builds multi-etapa copian solo los artefactos finales a la imagen de runtime — las herramientas de build, el código fuente y las dependencias de desarrollo se quedan en la etapa de construcción. El resultado: una imagen de runtime pequeña y segura. Nombra las etapas con AS para referenciarlas en COPY --from.
# stage 1: build
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# stage 2: runtime (small)
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]Seleccionar una etapa de build
--target construye solo hasta la etapa nombrada, saltándose las posteriores. Esto habilita un único Dockerfile para dev, test y producción: target 'test' para CI, 'final' para producción. BuildKit paraleliza automáticamente las etapas independientes.
# build only up to a named stage
# docker build --target builder -t myapp:dev .
FROM node:20 AS builder
RUN npm ci && npm run build
FROM node:20-alpine AS test
COPY --from=builder /app /app
RUN npm test
FROM nginx:alpine AS final
COPY --from=builder /app/dist /usr/share/nginx/html
# target a specific stage
# docker build --target test .Imágenes de runtime ligeras
Para binarios estáticos (Go, Rust), scratch produce la imagen más pequeña posible con superficie de ataque cero. Añade certificados CA para HTTPS. Distroless ofrece una base mínima con CAs raíz y usuario non-root, ideal para lenguajes dinámicos o cuando necesitas un runtime sin shell.
# build stage
FROM golang:1.21 AS builder
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -o app -ldflags="-s -w" .
# scratch = empty image, only the static binary
FROM scratch
COPY --from=builder /src/app /app
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
ENTRYPOINT ["/app"]
# result: ~10MB image
# or use distroless for a minimal OS base
FROM gcr.io/distroless/static
COPY --from=builder /src/app /app
ENTRYPOINT ["/app"]Patrón builder para lenguajes compilados
Compila en una imagen con el SDK completo y luego copia el artefacto a una imagen solo de runtime (JRE). Esto reduce drásticamente la imagen (JDK ~600MB vs JRE ~200MB) y quita las herramientas de build de producción. Precargar las dependencias antes de COPY mejora el caché de capas.
# stage 1: compile
FROM maven:3.9 AS builder
WORKDIR /build
COPY pom.xml .
RUN mvn dependency:go-offline
COPY src ./src
RUN mvn package -DskipTests
# stage 2: runtime with only the JRE
FROM eclipse-temurin:21-jre-alpine
COPY --from=builder /build/target/*.jar /app/app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app/app.jar"]
# benefits: no JDK, no source, no Maven cache in runtimeCopiar desde imágenes externas
COPY --from puede extraer de cualquier imagen — útil para ensamblar herramientas de varias bases sin una etapa de build. Las etapas también pueden referenciarse por índice (base 0), pero nombrarlas con AS es más claro. Fija las imágenes externas por digest para reproducibilidad.
# copy a binary from another image (no build stage needed)
FROM alpine:3.18
COPY --from=nginx:alpine /usr/sbin/nginx /usr/sbin/nginx
COPY --from=nginx:alpine /etc/nginx /etc/nginx
RUN apk add --no-cache libpcre2
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
# use a specific digest for reproducibility
COPY --from=redis:7@sha256:abc... /usr/local/bin/redis-server /usr/local/bin/
# copy from a built stage referenced by index
COPY --from=0 /build/output /appCaracterísticas de BuildKit
BuildKit desbloquea los cache mounts (las cachés de npm/pip persisten entre builds sin engordar la imagen), los secret mounts (las credenciales nunca tocan una capa), el reenvío SSH para repos privados y la sintaxis heredoc para RUN multilínea más limpios. Añade la directiva # syntax para fijar la versión del frontend del Dockerfile.
# enable BuildKit
# DOCKER_BUILDKIT=1 docker build .
# syntax directive for latest frontend
# syntax=docker/dockerfile:1
FROM alpine
# mount a cache (persists across builds, not in image)
RUN --mount=type=cache,target=/root/.npm npm ci
# mount a secret (never written to layers)
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci
# mount an SSH socket for private repos
RUN --mount=type=ssh git clone [email protected]:me/repo.git
# heredoc for multi-line scripts
RUN <<EOF
set -ex
apk add --no-cache curl
mkdir -p /app/data
EOFVolúmenes
Crear y usar volúmenes
Los volúmenes con nombre son gestionados por Docker y son la forma recomendada de persistir datos. Sobreviven a la eliminación del contenedor y son independientes del layout del sistema de archivos del host. El sufijo :ro monta en solo lectura. inspect revela la ruta en disco bajo /var/lib/docker/volumes.
# create a named volume
docker volume create mydata
# use it in a container
docker run -d -v mydata:/data alpine sh -c "sleep 1h"
# inspect the volume
docker volume inspect mydata
# mount read-only
docker run -v mydata:/data:ro alpine ls /data
# mount with a different filesystem (e.g. tmpfs)
docker run --tmpfs /cache alpine
# default volume driver: local
docker volume create --driver local mydataListar e inspeccionar volúmenes
ls lista los volúmenes con nombre; inspect muestra el driver y el punto de montaje. Para saber qué contenedores usan un volumen, filtra ps por volumen. Los volúmenes viven bajo /var/lib/docker/volumes/<nombre>/_data en hosts Linux — accede vía docker exec, no editando el host directamente.
# list all volumes
docker volume ls
# filter by name
docker volume ls -q --filter name=mydata
# show volume details (driver, mountpoint, options)
docker volume inspect mydata
# find the on-disk path
docker volume inspect --format '{{.Mountpoint}}' mydata
# find containers using a volume
docker ps -a --filter volume=mydata --format '{{.Names}}'
# check volume disk usage
docker system df -v | grep mydataDrivers de volumen
El driver local soporta NFS, dispositivos de bloque y tmpfs mediante opciones de montaje. Para almacenamiento en la nube (EBS, Azure Disk), usa un driver plugin. Los drivers abstraen el almacenamiento para que los contenedores se muevan entre hosts sin cambiar el comando run — clave para Swarm/Kubernetes.
# local driver (default, on host disk)
docker volume create --driver local mydata
# NFS volume
docker volume create --driver local \
--opt type=nfs \
--opt o=addr=10.0.0.5,rw \
--opt device=:/export/data nfsvol
# tmpfs (in-memory, ephemeral)
docker run --tmpfs /cache alpine
# block device
docker volume create --driver local \
--opt type=ext4 \
--opt device=/dev/sdb1 blockvol
# third-party drivers (e.g. cloud)
docker volume create --driver rexray/ebs ebsvolRespaldar volúmenes
Respalda un volumen montando tanto el volumen como un directorio del host en un contenedor temporal y luego tar del contenido. La restauración invierte el proceso. Este patrón funciona con cualquier driver de volumen y es la base de los scripts de respaldo automatizados.
# back up a volume to a tar file
docker run --rm -v mydata:/data -v $(pwd):/backup alpine \
tar czf /backup/mydata.tar.gz -C /data .
# restore a volume from a tar file
docker volume create mydata2
docker run --rm -v mydata2:/data -v $(pwd):/backup alpine \
tar xzf /backup/mydata.tar.gz -C /data
# migrate data between volumes
docker run --rm -v src:/src -v dst:/dst alpine \
cp -a /src/. /dst/
# snapshot using a temporary container
docker run --rm -v mydata:/data alpine ls -la /dataEliminar volúmenes
No se puede eliminar un volumen mientras un contenedor lo referencia (elimina primero el contenedor). prune elimina solo los volúmenes sin usar. La eliminación de volúmenes es irreversible — los datos se pierden para siempre. Respalda siempre los volúmenes de producción antes de hacer prune.
# remove a named volume (must not be in use)
docker volume rm mydata
# remove all unused volumes
docker volume prune
# remove volumes older than 24h not used
docker volume prune --filter "until=24h"
# force remove (even if a stopped container referenced it)
docker volume rm -f mydata
# remove with a label filter
docker volume prune --filter "label=temporary"
# CAUTION: data is gone permanently
docker volume rm mydataCompartir volúmenes entre contenedores
Varios contenedores pueden montar el mismo volumen para compartir estado. --volumes-from clona los montajes de volumen de otro contenedor — práctico para patrones sidecar. Añade :ro para los consumidores de solo lectura. Coordina las escrituras concurrentes para evitar corrupción; algunas apps necesitan un lock.
# share a volume between two containers
docker run -d --name db -v shared:/data alpine sleep 1h
docker run -d --name app -v shared:/data alpine sleep 1h
# use --volumes-from to copy a container's mounts
docker run -d --name helper --volumes-from db alpine sleep 1h
# read-only shared volume
docker run -d --name reader -v shared:/data:ro alpine sleep 1h
# compose: shared volume across services
# volumes:
# shared:
# services share 'shared' via volumes: ['shared:/data']
# verify both see the same data
docker exec db sh -c "echo hi > /data/msg"
docker exec app cat /data/msgBind mounts
Bind mount básico
Los bind mounts mapean una ruta del host directamente al contenedor — ideal para desarrollo en vivo donde las ediciones del host se reflejan al instante. Usa rutas absolutas del host. El sufijo :ro impide que el contenedor escriba de vuelta al host. La sintaxis moderna usa --mount por claridad.
# bind mount a host directory (modern syntax)
docker run -d --type bind --source $(pwd)/app --target /app nginx
# short form (-v)
docker run -d -v $(pwd)/app:/app nginx
# absolute host path required
docker run -v /home/me/app:/app nginx
# mount a single file
docker run -v /home/me/app.conf:/etc/app/app.conf:ro nginx
# mount read-only
docker run -v $(pwd)/app:/app:ro nginx
# compose equivalent
# volumes:
# - ./app:/appBind mount de solo lectura
Los montajes de solo lectura protegen la configuración del host de escrituras del contenedor — crítico por seguridad. --read-only hace que el sistema de archivos raíz entero sea inmutable, requiriendo montajes escritibles explícitos para /tmp y los directorios de logs. Esto endurece los contenedores ante compromisos.
# mount config read-only
docker run -v /etc/myapp:/etc/myapp:ro myapp
# --mount equivalent with explicit type
docker run --mount type=bind,source=/etc/myapp,target=/etc/myapp,readonly myapp
# read-only root filesystem (extra security)
docker run --read-only -v /tmp myapp
# combine read-only root with a writable tmpfs
docker run --read-only --tmpfs /tmp --tmpfs /var/cache myapp
# verify the mount is read-only
docker exec myapp touch /etc/myapp/test # should failFlujo de desarrollo
Monta el código fuente para que las ediciones del host se reflejen al instante en el contenedor. El truco del 'volumen anónimo para node_modules' evita que el node_modules vacío del host oculte las dependencias instaladas en la imagen. Puede hacer falta polling en Windows/Mac para un file-watch fiable.
# live-reload: mount source, run dev server
docker run -d -p 3000:3000 -v $(pwd)/src:/app/src node:20 \
sh -c "cd /app && npm run dev"
# mount node_modules separately (avoid host override)
docker run -d -v $(pwd):/app -v /app/node_modules node:20 npm start
# compose dev workflow
# services:
# web:
# volumes:
# - ./src:/app/src
# - /app/node_modules # anonymous, isolates deps
# hot reload with file watching (polling for Windows/Mac)
docker run -e CHOKIDAR_USEPOLLING=true -v $(pwd):/app node:20 npm startEtiquetas SELinux y AppArmor
En hosts con SELinux (RHEL/CentOS/Fedora), los bind mounts necesitan un sufijo :z o :Z para reetiquetar la ruta del host y que el contenedor pueda acceder. :z comparte la ruta entre contenedores; :Z la hace privada. Olvidar el sufijo provoca errores de 'permission denied'.
# SELinux: :z (shared) or :Z (private) suffix
docker run -v /host/path:/container/path:z myapp
docker run -v /host/path:/container/path:Z myapp
# :z labels the host path as shared among containers
# :Z labels it private to this container
# disable SELinux isolation (NOT recommended)
docker run --security-opt label=disable myapp
# AppArmor profile
docker run --security-opt apparmor=docker-default myapp
# custom AppArmor profile
docker run --security-opt apparmor=myprofile myappMount vs volume vs tmpfs
Volúmenes: gestionados por Docker, portables, lo mejor para datos persistentes. Bind mounts: rutas del host, lo mejor para desarrollo e inyección de configuración. tmpfs: en memoria, lo mejor para secretos y cachés efímeras. La sintaxis --mount es más explícita y más clara que -v.
# named volume (Docker-managed, portable)
docker run -v mydata:/data nginx
# bind mount (host path, host-dependent)
docker run -v /home/me/data:/data nginx
# --mount explicit syntax (recommended)
docker run --mount type=volume,source=mydata,target=/data nginx
docker run --mount type=bind,source=/home/me/data,target=/data nginx
docker run --mount type=tmpfs,target=/cache nginx
# tmpfs (in-memory, ephemeral, fast)
docker run --tmpfs /cache nginx
# tmpfs with size limit
docker run --mount type=tmpfs,target=/cache,tmpfs-size=64m nginxBind mounts en Compose
En Compose, una ruta relativa (./html) crea un bind mount, mientras que un nombre (logs) que referencia la sección volumes: crea un volumen con nombre. Una ruta absoluta (/cache) crea un volumen anónimo. La sintaxis larga hace explícitas opciones como read_only.
# docker-compose.yml
services:
web:
image: nginx
volumes:
# relative host path = bind mount
- ./html:/usr/share/nginx/html:ro
# named volume
- logs:/var/log/nginx
# anonymous volume
- /cache
volumes:
logs: # declare named volumes here
# use ~ (tilde) — Compose expands it
volumes:
- ~/config:/etc/app:ro
# long-form syntax with options
volumes:
- type: bind
source: ./html
target: /usr/share/nginx/html
read_only: trueRedes
Red bridge (por defecto)
La red bridge por defecto carece de DNS automático — los contenedores deben usar IPs. Las redes bridge personalizadas proporcionan descubrimiento de servicios por DNS: los contenedores se resuelven entre sí por nombre. Por eso Compose crea automáticamente una red personalizada para cada proyecto.
# the default bridge network (named 'bridge')
docker run -d --name web nginx
# create a custom bridge network (recommended)
docker network create mynet
# attach a container to a custom network
docker run -d --name web --network mynet nginx
docker run -d --name db --network mynet postgres
# containers on the same custom network can resolve by name
docker exec web ping db # DNS resolves 'db'
# the default bridge does NOT support DNS names
# always use a custom bridge for multi-container appsRed host
La red de tipo host elimina el namespace de red — el contenedor comparte las interfaces y puertos del host. Ofrece el mejor rendimiento pero sacrifica el aislamiento y el mapeo de puertos. Solo disponible en Linux; en Mac/Windows se mapea a la red de una VM, no al host.
# use the host's network stack directly (no isolation)
docker run --network host nginx
# host network disables port mapping
# -p is ignored when --network host is used
# useful for performance-sensitive apps
docker run --network host -d myapp
# only works on Linux (not Docker Desktop on Mac/Windows)
# inspect host network
docker network inspect host
# bound to host interfaces — be careful with privileged ports
docker run --network host --cap-add NET_ADMIN myappRed overlay (Swarm)
Las redes overlay abarcan varios nodos Swarm, habilitando comunicación segura entre hosts con DNS integrado. --attachable permite que contenedores independientes se unan a un overlay (útil para depurar). El cifrado protege el tráfico entre nodos; actívalo para cargas sensibles.
# create an overlay network (requires Swarm mode)
docker network create -d overlay myoverlay
# overlay with encryption
docker network create -d overlay -o encrypted myoverlay
# deploy a service on the overlay
docker service create --network myoverlay --name web nginx
# multi-host communication for Swarm services
# containers on different nodes resolve by service name
# node-local network bridged to overlay
docker network create -d overlay --attachable myoverlay
docker run -d --network myoverlay alpine # standalone containerRedes personalizadas
Las redes personalizadas te permiten controlar subredes, gateways y aislamiento. --internal impide el acceso saliente a internet. macvlan da a los contenedores una presencia real en la LAN física (cada uno con su propia MAC) — útil para apps heredadas pero rompe por defecto la comunicación host-contenedor.
# create a bridge network with a subnet
docker network create --subnet 172.20.0.0/16 mynet
# assign a static IP
docker run -d --network mynet --ip 172.20.0.10 nginx
# set a custom gateway
docker network create --subnet 172.20.0.0/16 \
--gateway 172.20.0.1 mynet
# restrict to internal only (no external access)
docker network create --internal mynet
# specify a driver and options
docker network create -d bridge \
-o com.docker.network.bridge.name=br0 mynet
# macvlan (container gets a MAC on the physical network)
docker network create -d macvlan \
--subnet 192.168.1.0/24 -o parent=eth0 mymacvlanDNS de contenedores
El DNS integrado de Docker (127.0.0.11) resuelve los nombres de contenedor en redes definidas por el usuario. El bridge por defecto no tiene DNS. --dns añade resolutores externos; --add-host inyecta entradas estáticas. Usa nombres de servicio (no IPs) para la comunicación entre contenedores y que los redespliegues no rompan el DNS.
# containers on custom networks resolve by name
docker network create mynet
docker run -d --name db --network mynet postgres
docker run -it --network mynet alpine nslookup db
# the embedded DNS server is at 127.0.0.11
docker exec web cat /etc/resolv.conf
# add custom DNS servers
docker run --dns 8.8.8.8 alpine nslookup example.com
# add DNS search domains
docker run --dns-search example.com alpine nslookup myhost
# add a host entry (like /etc/hosts)
docker run --add-host myservice:10.0.0.5 alpine ping myservice
# extra hosts in compose
# extra_hosts:
# - "myservice:10.0.0.5"Inspección y gestión de redes
network connect/disconnect permite adjuntar un contenedor en marcha a redes adicionales sin reiniciar — útil para sidecars. inspect muestra los contenedores conectados, la subred y el driver. prune elimina las redes no usadas por ningún contenedor.
# list all networks
docker network ls
# inspect a network (containers, IPAM, driver)
docker network inspect mynet
# see which containers are on a network
docker network inspect --format '{{range .Containers}}{{.Name}} {{end}}' mynet
# connect a running container to another network
docker network connect mynet2 web
# disconnect a container from a network
docker network disconnect mynet web
# remove an unused network
docker network rm mynet
docker network pruneMapeo de puertos
Mapeo de puertos básico
-p host:contenedor mapea un puerto del host a uno del contenedor. Si omites el puerto del host, Docker elige uno (usa docker port para encontrarlo). Cada puerto del host solo puede mapear a un contenedor — usa un proxy inverso o puertos de host distintos para varias instancias.
# map host:container
docker run -d -p 8080:80 nginx
# map to a random host port
docker run -d -p 80 nginx
docker port $(docker ps -lq) 80 # find the assigned port
# map multiple ports
docker run -d -p 8080:80 -p 8443:443 nginx
# map the same port on host and container
docker run -d -p 80:80 nginx
# explicit protocol (default tcp)
docker run -d -p 53:53/udp dns
# long form
docker run -d --publish 8080:80 nginxEnlazar a una IP específica
Anteponer una IP controla a qué interfaz se enlaza el puerto. 127.0.0.1 mantiene el servicio solo local — esencial para bases de datos que no quieres exponer. 0.0.0.0 (por defecto) se enlaza a todas las interfaces. Enlaza siempre las bases de datos a localhost en producción.
# bind to a specific host IP
docker run -d -p 127.0.0.1:8080:80 nginx
# bind to localhost only (not exposed externally)
docker run -d -p 127.0.0.1:5432:5432 postgres
# bind to all interfaces (default)
docker run -d -p 0.0.0.0:8080:80 nginx
# bind to an IPv6 address
docker run -d -p [::1]:8080:80 nginx
# multiple bindings
docker run -d -p 127.0.0.1:8080:80 -p 0.0.0.0:8443:443 nginx
# compose: specify IP
# ports:
# - "127.0.0.1:5432:5432"Puertos UDP y SCTP
El sufijo /udp o /sctp selecciona el protocolo; TCP es el por defecto. Para servicios como DNS que necesitan ambos, declara ambos mapeos. Los rangos de puertos se mapean 1:1 entre host y contenedor — útil para WebRTC, RTP o FTP pasivo. Asegúrate de que las reglas del firewall coincidan con los protocolos.
# UDP port (DNS, syslog, statsd)
docker run -d -p 53:53/udp coredns
# both TCP and UDP
docker run -d -p 53:53/tcp -p 53:53/udp coredns
# SCTP (e.g. telecom signaling)
docker run -d -p 3868:3868/sctp myapp
# range of ports (host range maps to container range)
docker run -d -p 8000-8100:8000-8100 myapp
# UDP range
docker run -d -p 50000-50010:50000-50010/udp myapp
# compose with protocol
# ports:
# - "53:53/udp"Rango de puertos
Los rangos de puertos se mapean 1:1 (host 8000-8005 al contenedor 8000-8005). -P (mayúscula) publica automáticamente cada puerto EXPOSE en un puerto alto aleatorio del host — práctico para pruebas rápidas. Usa docker ps para ver los mapeos reales cuando los puertos son aleatorios.
# map a range of host ports to container ports
docker run -d -p 8000-8005:8000-8005 myapp
# map host range to a single container port (NOT supported)
# this maps range-to-range only
# random port for each (useful for testing)
docker run -d -p 80 -p 443 nginx
docker port $(docker ps -lq)
# expose a range with EXPOSE (documentation only)
# EXPOSE 8000-8005
# publish all exposed ports at once
docker run -d -P nginx # capital P publishes all EXPOSE ports
# view the random mappings
docker ps --format '{{.Names}} {{.Ports}}'Exponer vs publicar
EXPOSE documenta la intención; -p realmente publica. En Compose, expose comparte un puerto solo con otros servicios de la misma red, mientras que ports publica al host. Esta distinción importa para bases de datos: expón internamente, nunca publiques al host en producción.
# Dockerfile: EXPOSE is documentation, NOT a publish
EXPOSE 80 443
# runtime: -p PUBLISHES the port to the host
docker run -d -p 8080:80 nginx
# -P publishes all EXPOSE ports to random host ports
docker run -d -P nginx
# compose: expose vs ports
services:
web:
image: nginx
expose:
- "80" # only to linked services, NOT to host
ports:
- "8080:80" # published to the host
# view exposed (not published) ports
docker inspect --format '{{json .Config.ExposedPorts}}' nginxMapeo de puertos aleatorio
Omitir el puerto del host deja que Docker elija un puerto efímero aleatorio (32768-60999 por defecto). Usa docker port o docker ps para descubrirlo. Es útil para escalar servicios idénticos en un host. Ajusta el rango efímero en /proc/sys/net/ipv4/ip_local_port_range en Linux.
# publish to a random high host port
docker run -d -p 80 nginx
# publish all EXPOSE ports randomly
docker run -d -P nginx
# find the assigned port
docker port <container> 80
docker port <container>
# see mappings in ps output
docker ps --format 'table {{.Names}} {{.Ports}}'
# prefer a range for random allocation
docker run -d -p 30000-40000:80 nginx
# compose: random host port
# ports:
# - "80" # random host port, container port 80Variables de entorno
Fijar variables de entorno
-e (o --env) fija variables de entorno en el contenedor. -e VAR (sin valor) hereda la variable del shell del host. Para valores sensibles, prefiere --env-file o Docker secrets antes que -e plano, que es visible en docker inspect y en los listados de procesos.
# single variable
docker run -d -e MYSQL_ROOT_PASSWORD=secret mysql
# multiple variables
docker run -d \
-e MYSQL_ROOT_PASSWORD=secret \
-e MYSQL_DATABASE=mydb \
-e MYSQL_USER=app \
mysql
# pass from the host environment
docker run -d -e HOST_PWD mysql
# HOST_PWD in the container = $HOST_PWD on host
# set a variable without a value (passes host value or empty)
docker run -e DEBUG alpine env
# long form
docker run --env MYSQL_ROOT_PASSWORD=secret mysqlArchivos env
--env-file carga variables de un archivo, manteniendo el comando run limpio y los secretos fuera del historial del shell. Compose carga automáticamente un .env de nivel superior para la sustitución de variables en el propio archivo compose. Los comentarios (#) y las líneas en blanco se ignoran; las comillas se conservan literalmente.
# .env file
# DB_HOST=db
# DB_USER=app
# DB_PASSWORD=secret
# load variables from a file
docker run --env-file .env myapp
# load multiple env files
docker run --env-file .env --env-file .env.local myapp
# Compose reads .env automatically for variable substitution
# and supports env_file per service:
# services:
# web:
# env_file:
# - .env
# - .env.local
# env file with comments and blank lines
docker run --env-file config.env myappVariables de entorno en el Dockerfile
ENV hornea las variables en la imagen, visibles en build y runtime. ARG es solo de build — conviértelo a ENV si el runtime lo necesita. Sobrescribe los valores horneados con -e en ejecución. Ojo: las variables de entorno son visibles en docker inspect, así que no guardes secretos ahí.
# ENV sets a persistent variable
ENV NODE_ENV=production
ENV PATH=/app/bin:$PATH
# use ARG for build-time only, ENV for runtime
ARG BUILD_VERSION=1.0
ENV APP_VERSION=${BUILD_VERSION}
# view all env vars
docker exec web env
# inspect a specific variable
docker exec web printenv NODE_ENV
# override at runtime
docker run -e NODE_ENV=development myapp
# set via Compose
# environment:
# - NODE_ENV=development
# - DEBUG=trueVariables dinámicas y sustitución
La expansión del shell ($(...) o ${VAR}) ocurre en el host antes de que Docker vea el valor. En Compose, ${VAR} se sustituye desde el archivo .env. En CMD en forma exec, ${VAR} NO se expande — envuélvelo con sh -c. Pasa el UID del host para una propiedad de archivos correcta en los bind mounts.
# pass a computed value at runtime
docker run -e STARTUP_TIME=$(date +%s) myapp
# use host shell expansion
docker run -e USER_ID=$(id -u) myapp
# Compose variable substitution from .env
# services:
# web:
# environment:
# DB_HOST: ${DB_HOST}
# .env file:
# DB_HOST=db
# Compose with default values
# DB_HOST: ${DB_HOST:-localhost}
# pass the current user for permission matching
docker run -u $(id -u):$(id -g) -e HOME=/tmp myapp
# resolve env at runtime with sh -c (not in exec form)
ENV PORT=3000
CMD ["sh", "-c", "node server.js --port ${PORT}"]Entorno en Compose
El environment de Compose acepta sintaxis de lista o de mapa. env_file carga los valores en el contenedor; .env (nivel superior) proporciona variables para la sustitución ${} en el propio archivo compose. Usa la forma de mapa por legibilidad con muchas variables.
# docker-compose.yml
services:
web:
image: myapp
environment:
- NODE_ENV=production
- DEBUG=false
- DB_HOST=db
# map form (cleaner for many vars)
environment:
NODE_ENV: production
DB_HOST: db
db:
image: postgres
env_file:
- .env.db
environment:
POSTGRES_DB: ${DB_NAME} # from .env
# top-level .env for substitution
# DB_NAME=mydbGestión de secretos
Los secretos se montan como archivos bajo /run/secrets, nunca como variables de entorno, y están cifrados en tránsito y en reposo en Swarm. Evita hornear secretos en las imágenes (ENV) o pasarlos vía -e — ambos se filtran vía docker inspect y las capas de la imagen. Los secret mounts de BuildKit mantienen las credenciales de build fuera de las capas.
# Docker Swarm secrets (encrypted, mounted as files)
echo "supersecret" | docker secret create db_password -
docker service create --secret db_password myapp
# read in the app
# cat /run/secrets/db_password
# Compose secrets (v3.1+)
# services:
# web:
# secrets:
# - db_password
# secrets:
# db_password:
# file: ./secrets/db_password.txt
# BuildKit secret mount (build-time, not in layers)
# RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci
# avoid: baking secrets in ENV or -e (visible in inspect)
docker run -e API_KEY=xxx myapp # NOT recommendedFundamentos de Docker Compose
docker-compose.yml básico
Compose define una app multi-contenedor en un único archivo YAML. services describe cada contenedor; volumes y networks se declaran en el nivel superior. depends_on controla el orden de arranque. docker compose up -d inicia la pila en segundo plano.
# docker-compose.yml (Compose spec v2)
services:
web:
image: nginx:alpine
ports:
- "8080:80"
volumes:
- ./html:/usr/share/nginx/html:ro
depends_on:
- db
restart: unless-stopped
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: secret
volumes:
- dbdata:/var/lib/postgresql/data
volumes:
dbdata:
# run: docker compose up -dComandos de Compose
up crea e inicia, down detiene y elimina. Añade -v a down para borrar volúmenes (pérdida de datos). exec ejecuta un comando en un servicio en marcha; run inicia un contenedor nuevo para una tarea puntual. --scale lanza varias réplicas de un servicio en el mismo host.
# start all services (foreground)
docker compose up
# start in background (detached)
docker compose up -d
# rebuild images before starting
docker compose up -d --build
# stop and remove containers (keeps volumes)
docker compose down
# also remove volumes (data loss)
docker compose down -v
# view logs (all services)
docker compose logs -f
# scale a service
docker compose up -d --scale worker=3
# run a one-off command in a service
docker compose exec web sh
docker compose run --rm web python manage.py migrateDependencias de servicios
depends_on controla el orden de arranque, pero la dependencia puede no estar 'lista' — usa condition: service_healthy con un healthcheck para esperar hasta que la base de datos acepte conexiones. service_completed_successfully espera a los contenedores de inicialización. Las apps aún deberían reintentar conexiones.
services:
web:
image: myapp
depends_on:
db:
condition: service_healthy
redis:
condition: service_started
restart: on-failure
db:
image: postgres
healthcheck:
test: ["CMD", "pg_isready", "-U", "postgres"]
interval: 5s
retries: 5
redis:
image: redis
# conditions: service_started | service_healthy | service_completed_successfullyBuild en Compose
build define cómo construir una imagen desde el código; image etiqueta el resultado. context se envía al constructor (mantenlo pequeño). target selecciona una etapa de build multi-etapa. --build fuerza un rebuild en up. Los build args pasan valores en tiempo de build.
services:
web:
build:
context: ./app
dockerfile: Dockerfile.prod
args:
VERSION: 1.0
target: final
image: myapp:1.0
ports:
- "8080:80"
worker:
build: ./worker # shorthand: context only
image: myworker:1.0
# build and tag
docker compose build
docker compose build --no-cache web
docker compose up -d --buildVolúmenes en Compose
Una ruta relativa (./html) es un bind mount; un nombre (logs) declarado bajo volumes: de nivel superior es un volumen con nombre; una ruta absoluta (/cache) es anónimo. Los volúmenes con nombre pueden especificar un driver y opciones (por ejemplo, NFS). Compose antepone el nombre del proyecto a los nombres de volumen.
services:
web:
image: nginx
volumes:
# named volume
- logs:/var/log/nginx
# bind mount (relative path)
- ./html:/usr/share/nginx/html:ro
# anonymous volume
- /cache
db:
image: postgres
volumes:
- dbdata:/var/lib/lib/postgresql/data
volumes:
logs:
dbdata:
driver: local
driver_opts:
type: nfs
device: ":/export/data"
o: addr=10.0.0.5,rwRedes en Compose
Compose crea una red por defecto para el conjunto de servicios, pero definir redes personalizadas permite aislar capas. web hace de puente entre frontend y backend. internal: true bloquea el acceso a internet del backend. Los servicios de la misma red se resuelven entre sí por nombre de servicio vía DNS.
services:
web:
image: nginx
networks:
- frontend
- backend
db:
image: postgres
networks:
- backend
proxy:
image: traefik
networks:
- frontend
networks:
frontend:
driver: bridge
backend:
driver: bridge
internal: true # no external access
# custom subnet
networks:
backend:
ipam:
config:
- subnet: 172.28.0.0/16Docker Compose avanzado
Perfiles de Compose
Los perfiles agrupan servicios opcionales. Los servicios sin perfil arrancan siempre; los servicios con perfil solo arrancan cuando su perfil se activa con --profile. Esto permite que un archivo compose sirva para dev, test y prod: habilita los perfiles selectivamente por entorno.
services:
web:
image: nginx
profiles: ["default", "prod"]
debug:
image: nginx
profiles: ["debug"]
ports:
- "8080:80"
test:
image: myapp-test
profiles: ["test"]
# start only default services
docker compose up -d
# start with the debug profile
docker compose --profile debug up -d
# run tests
docker compose --profile test run test
# start multiple profiles
docker compose --profile prod --profile debug up -dAnulaciones de Compose
Compose carga automáticamente docker-compose.override.yml sobre docker-compose.yml para personalizar el desarrollo local. Para otros entornos, pasa varios archivos -f en orden — los últimos sobrescriben a los primeros. Esto separa de forma limpia la configuración base de los ajustes específicos por entorno.
# docker-compose.yml (base)
services:
web:
image: myapp:latest
environment:
NODE_ENV: production
# docker-compose.override.yml (auto-loaded for dev)
services:
web:
build: ./app
environment:
NODE_ENV: development
DEBUG: "true"
volumes:
- ./src:/app/src
command: npm run dev
# explicit override file
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
# merge order: later files override earlier ones
# docker compose -f base.yml -f dev.yml -f local.yml upHealthchecks en Compose
Los healthchecks de Compose reflejan el HEALTHCHECK del Dockerfile. start_period concede un tiempo de gracia durante el arranque. Combinar healthcheck con depends_on: condition: service_healthy hace que un servicio espere hasta que sus dependencias estén realmente listas, no solo iniciadas.
services:
web:
image: nginx
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
db:
image: postgres
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
timeout: 5s
retries: 5
app:
image: myapp
depends_on:
db:
condition: service_healthyEscalado y réplicas
--scale lanza N contenedores idénticos en un host — el servicio no debe enlazar un puerto de host fijo (usa un puerto aleatorio o sin mapeo de host). La clave deploy.replicas la respeta Swarm; para Compose puro usa --scale. Un balanceador se sitúa delante de los servicios escalados.
# scale at startup (single host)
docker compose up -d --scale worker=4
# docker-compose.yml with replicas (Compose spec)
services:
worker:
image: myworker
deploy:
replicas: 4
resources:
limits:
cpus: "0.5"
memory: 512M
web:
image: nginx
deploy:
replicas: 2
update_config:
parallelism: 1
delay: 10s
# note: replicas deploy key is for Swarm;
# plain Compose uses --scale
# prevent port conflicts when scaling
docker compose up -d --scale web=3 # web must use random portsConfig y validación de Compose
config valida y renderiza el archivo compose fusionado (incluyendo overrides y la sustitución de .env), lo cual es inestimable para depurar. --services, --images y --volumes inventarían los recursos. Usa -q en CI para fallar rápido ante archivos compose malformados.
# validate and print the merged compose file
docker compose config
# check for errors only
docker compose config -q
# list all services
docker compose config --services
# list all images used
docker compose config --images
# list all volumes
docker compose config --volumes
# render with variable substitution (resolve .env)
docker compose config > rendered.yml
# validate before deploying
docker compose config -q && docker compose up -dMúltiples archivos Compose
Apilar archivos compose separa preocupaciones: configuración base, anulaciones por entorno, ajustes locales. COMPOSE_FILE (separado por dos puntos en Linux/Mac, punto y coma en Windows) evita repetir -f. Las listas como ports se añaden; los mapas como environment se fusionan por clave.
# base, dev, and prod files
docker compose -f docker-compose.yml -f docker-compose.dev.yml up
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
# COMPOSE_FILE env var (avoids -f repetition)
export COMPOSE_FILE=docker-compose.yml:docker-compose.dev.yml
docker compose up -d
# docker-compose.prod.yml
services:
web:
image: registry.com/myapp:${TAG}
environment:
NODE_ENV: production
deploy:
replicas: 3
# difference files: add/override specific keys
# lists (ports, volumes) are merged; maps (environment) are mergedRegistro de Docker
Ejecutar un registro local
La imagen registry:2 ejecuta un registro privado en el puerto 5000. Monta un volumen para persistir imágenes. Para hosts remotos o HTTPS, configura certificados TLS o añade el registro a insecure-registries en /etc/docker/daemon.json. La API v2 permite catalogar repositorios vía curl.
# run the official registry image
docker run -d -p 5000:5000 --name registry \
-v registrydata:/var/lib/registry \
--restart always \
registry:2
# tag and push to it
docker tag myapp:1.0 localhost:5000/myapp:1.0
docker push localhost:5000/myapp:1.0
# pull from it
docker pull localhost:5000/myapp:1.0
# list repositories in the registry
curl http://localhost:5000/v2/_catalog
# list tags for a repository
curl http://localhost:5000/v2/myapp/tags/listPublicar en un registro privado
Las imágenes deben etiquetarse con el host del registro antes de hacer push. Para registros con certificados self-signed, añade el host a insecure-registries y reinicia el daemon (no recomendado para producción — usa una CA real o una CA interna). push -a sube cada tag del repositorio.
# tag with the registry URL
docker tag myapp:1.0 registry.local:5000/myapp:1.0
# login
docker login registry.local:5000
# push
docker push registry.local:5000/myapp:1.0
# push all tags
docker push -a registry.local:5000/myapp
# verify it landed
curl http://registry.local:5000/v2/myapp/tags/list
# self-signed cert: configure the daemon
# /etc/docker/daemon.json:
# { "insecure-registries": ["registry.local:5000"] }
# then: systemctl restart dockerDescargar de un registro privado
Descarga de un registro privado especificando el nombre completo de la imagen. Las credenciales de login se guardan en ~/.docker/config.json (usa un credential helper por seguridad). Para CI/CD, guarda las credenciales como secretos y haz login antes de descargar. Fija por digest para despliegues reproducibles.
# login first (credentials cached in ~/.docker/config.json)
docker login registry.local:5000
# pull by full name
docker pull registry.local:5000/myapp:1.0
# pull by digest (immutable)
docker pull registry.local:5000/myapp@sha256:abc123...
# use in Compose
# services:
# web:
# image: registry.local:5000/myapp:1.0
# logout
docker logout registry.local:5000
# check stored credentials
cat ~/.docker/config.jsonAutenticación del registro
Asegura un registro con htpasswd basic auth o un servidor de tokens (OAuth). Para TLS, monta los certificados y escucha en el 443. Los credential helpers (credsStore) guardan las contraseñas en el keychain del sistema operativo en lugar del config.json en texto plano — esencial para máquinas compartidas o de CI.
# htpasswd-based auth
mkdir -p auth
docker run --entrypoint htpasswd httpd:2 -Bbn user password > auth/htpasswd
# run registry with auth
docker run -d -p 5000:5000 --name registry \
-v $(pwd)/auth:/auth \
-e REGISTRY_AUTH=htpasswd \
-e REGISTRY_AUTH_HTPASSWD_REALM=Registry \
-e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
registry:2
# login now required
docker login localhost:5000
# token-based auth (OAuth, JWT) for enterprise
# configure REGISTRY_AUTH=token with an auth server
# credential helpers (avoid storing in config.json)
# "credsStore": "secretservice" (Linux)
# "credsStore": "osxkeychain" (Mac)
# "credsStore": "wincred" (Windows)API del registro
La API HTTP v2 del registro permite scriptar la gestión del registro. _catalog lista los repos; los manifests describen las capas de la imagen. La eliminación exige REGISTRY_STORAGE_DELETE_ENABLED=true y elimina manifests — los blobs se limpian con la recolección de basura (registry garbage-collect).
# list all repositories
curl http://localhost:5000/v2/_catalog
# list tags for a repo
curl http://localhost:5000/v2/myapp/tags/list
# get a manifest
curl -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
http://localhost:5000/v2/myapp/manifests/1.0
# delete a manifest (by digest)
curl -X DELETE \
http://localhost:5000/v2/myapp/manifests/sha256:abc123...
# enable delete API
# -e REGISTRY_STORAGE_DELETE_ENABLED=true
# check if a blob exists
curl -I http://localhost:5000/v2/myapp/blobs/sha256:abc...Recolección de basura
Eliminar un manifest deja blobs huérfanos hasta que corra la recolección de basura. Detén el registro (o usa --dry-run) para no recoger capas en uso. Programa GC regularmente en producción para recuperar disco de imágenes eliminadas o sustituidas. La ruta config.yml es el archivo de configuración del registro.
# run garbage collection on a registry
docker exec -it registry \
garbage-collect --dry-run /etc/docker/registry/config.yml
# actual collection (stop the registry first for consistency)
docker stop registry
docker run --rm -v registrydata:/var/lib/registry \
-v /path/config.yml:/etc/docker/registry/config.yml \
registry:2 garbage-collect /etc/docker/registry/config.yml
docker start registry
# delete unreferenced blobs after manifest deletion
# schedule GC as a cron job for production registries
# view disk usage
docker exec registry du -sh /var/lib/registryDocker Hub
Login y logout
Prefiere los tokens de acceso a las contraseñas — son revocables y con ámbito limitado. --password-stdin lee de stdin, evitando la contraseña en el historial del shell y en los listados de procesos. Configura un credential helper para guardar las credenciales en el keychain del SO en lugar del config.json en texto plano.
# interactive login (prompts for username/password)
docker login
# login with a token (recommended over password)
docker login -u username -p dckr_pat_xxxxx
# login via stdin (avoids shell history)
echo "dckr_pat_xxxxx" | docker login -u username --password-stdin
# logout
docker logout
# credentials stored in ~/.docker/config.json
# or OS keychain via credential helper
# create an access token on Docker Hub
# Account Settings -> Security -> New Access TokenBuscar imágenes
docker search consulta Docker Hub desde la CLI, con filtros por estrellas, estatus oficial y builds automatizados. Las imágenes oficiales (library/nginx) están auditadas por Docker — prefiérelas como bases. La interfaz web ofrece filtrado más rico por SO, arquitectura y categoría.
# search Docker Hub from the CLI
docker search nginx
# filter by stars
docker search --filter stars=100 nginx
# only official images
docker search --filter is-official nginx
# only automated builds
docker search --filter is-automated nginx
# limit results
docker search --limit 5 nginx
# show full description (no truncation)
docker search --no-trunc nginx
# search on the web for richer filtering
# https://hub.docker.com/search?q=nginxPublicar en Docker Hub
Etiqueta las imágenes como usuario/repo:tag y luego haz push para publicar en Docker Hub. El repositorio se crea automáticamente en el primer push (público por defecto). push -a sube cada tag. Las cuentas gratuitas obtienen un repo privado; los planes de pago ofrecen más. Fija la visibilidad del repositorio en la interfaz web de Hub.
# tag with your username
docker tag myapp:1.0 username/myapp:1.0
# also tag as latest
docker tag username/myapp:1.0 username/myapp:latest
# login
docker login
# push (creates the repo if it doesn't exist)
docker push username/myapp:1.0
docker push username/myapp:latest
# push all tags
docker push -a username/myapp
# make the repo private on Docker Hub
# (Hub web UI -> Repository -> Settings -> Make Private)Builds automatizados
Los autobuilds de Docker Hub enlazan un repo git y construyen en cada push. Los flujos modernos prefieren GitHub Actions con buildx y push, que ofrecen más control, caché y builds multi-arquitectura. Los autobuilds de Hub siguen siendo una opción de bajo esfuerzo para proyectos simples.
# connect a GitHub/Bitbucket repo to Docker Hub
# Hub web UI -> Create -> Build Rule
# build rule examples:
# Source: github.com/me/myapp Branch: main
# Dockerfile location: /Dockerfile
# Image tag: latest
# trigger a build via webhook
curl -H "Content-Type: application/json" \
--data '{"build": true}' \
https://hub.docker.com/api/build/v1/source/.../trigger/.../call/
# build context with multiple tags and stages
# Source: Branch main -> Tag: branch-main
# Source: Tag v1.0 -> Tag: 1.0, latest
# Autobuild triggers on git push
# (deprecated in favor of GitHub Actions)Organizaciones y equipos
Las organizaciones comparten repositorios entre un equipo con acceso basado en roles. Los equipos obtienen permisos por repositorio (lectura, escritura, administración). Las cuentas de servicio proporcionan tokens no personales para CI/CD — revocables y rotables sin afectar a individuos. Usa el namespacing orgname/repo.
# create an organization on Docker Hub
# (web UI: Create Organization)
# create a team and add members
# Org -> Teams -> Create Team -> Add Members
# assign repository permissions per team
# Repository -> Permissions -> Add Team
# Read-only, Read-write, Admin
# create a service account token for CI
# Org -> Service Accounts -> New Service Account
# use the token in CI: docker login -u tokenname -p token
# team namespaces: orgname/repo
docker tag myapp orgname/myapp:1.0
docker push orgname/myapp:1.0Confianza en imágenes (DCT)
Docker Content Trust (DCT) usa Notary para firmar los tags de imagen, asegurando que la imagen que descargas es la que publicó quien la creó. Actívalo con DOCKER_CONTENT_TRUST=1. Con DCT activado, solo se pueden descargar o publicar imágenes firmadas. Gestiona las claves de firma con cuidado — perderlas puede bloquearte el acceso a tus imágenes.
# enable Docker Content Trust (signing)
export DOCKER_CONTENT_TRUST=1
# push signs the image automatically
docker push username/myapp:1.0
# pull refuses unsigned images when DCT is on
docker pull username/myapp:1.0
# disable for a single command
DOCKER_CONTENT_TRUST=0 docker pull unsigned/myapp:1.0
# generate delegation keys
docker trust key generate alice
# add a signer to a repository
docker trust signer add --key alice.pub alice username/myapp
# view signatures
docker trust inspect username/myapp:1.0
# revoke and rotate keys via the notary CLIHealthcheck
Healthcheck básico
Un healthcheck ejecuta un comando periódicamente; salida 0 es saludable, no cero es no saludable. El contenedor arranca en 'starting' y pasa a 'healthy' tras reintentos exitosos, o 'unhealthy' tras fallar los reintentos. start_period da un tiempo de gracia durante el arranque. El estado de salud guía las decisiones de reinicio de Swarm.
# add a healthcheck at runtime
docker run -d --name web \
--health-cmd="curl -f http://localhost/ || exit 1" \
--health-interval=30s \
--health-timeout=5s \
--health-retries=3 \
--health-start-period=10s \
nginx
# check health status
docker inspect --format '{{.State.Health.Status}}' web
# view health check log (last 5 results)
docker inspect --format '{{json .State.Health.Log}}' web | jq
# states: starting | healthy | unhealthy | noneHealthcheck en el Dockerfile
HEALTHCHECK en un Dockerfile hornea la comprobación en la imagen. Usa la comprobación más ligera que confirme que la app realmente sirve — curl -f o wget --spider para HTTP, pg_isready para Postgres. HEALTHCHECK NONE desactiva una comprobación heredada. Las comprobaciones demasiado amplias causan parpadeos falsos de 'unhealthy'.
FROM nginx:alpine
# basic healthcheck (exec form)
HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=10s \
CMD curl -f http://localhost/ || exit 1
# using wget (alpine)
HEALTHCHECK CMD wget --spider -q http://localhost/ || exit 1
# postgres ships a ready check
HEALTHCHECK CMD pg_isready -U postgres
# disable a healthcheck inherited from the base image
HEALTHCHECK NONE
# verify
docker inspect --format '{{.Config.Healthcheck}}' myappOpciones del healthcheck
interval fija la frecuencia de comprobación; timeout acota cada comprobación; retries es el umbral de fallos consecutivos. start_period ignora los fallos durante el arranque, evitando 'unhealthy' falsos mientras la app se calienta. Ajusta estos valores para detectar caídas reales rápido sin parpadeos bajo carga.
# full set of options
HEALTHCHECK \
--interval=30s \ # time between checks (default 30s)
--timeout=5s \ # max time per check (default 30s)
--retries=3 \ # failures to mark unhealthy (default 3)
--start-period=30s \ # boot grace period (default 0s)
CMD curl -f http://localhost/
# interval: how often to run
# timeout: if a check exceeds this, it's a failure
# retries: consecutive failures before unhealthy
# start-period: failures during this don't count
# compose form
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"]
interval: 30s
timeout: 5s
retries: 3
start_period: 30sInspeccionar el estado de salud
ps muestra (healthy)/(unhealthy) junto al estado. El Health.Log registra las últimas 5 salidas de comprobación — inestimable para depurar por qué falla una comprobación. Ejecuta el comando de comprobación manualmente vía exec para ver el error real. Filtra ps por health para encontrar contenedores enfermos rápido.
# current status
docker inspect --format '{{.State.Health.Status}}' web
# last 5 check results
docker inspect --format '{{range .State.Health.Log}}\
{{.ExitCode}} {{.Output}}{{end}}' web
# show in ps (status column shows (healthy)/(unhealthy))
docker ps
# filter containers by health
docker ps --filter "health=unhealthy"
# troubleshoot a failing check
docker inspect --format '{{json .State.Health.Log}}' web | jq
# run the check command manually
docker exec web curl -f http://localhost/Healthcheck en Compose
El healthcheck de Compose refleja el del Dockerfile. test acepta un array (forma exec) o una cadena CMD-SHELL. disable: true elimina una comprobación heredada. Emparéjalo con depends_on: condition: service_healthy para que un servicio espere a que las dependencias estén realmente listas, no solo iniciadas.
services:
web:
image: nginx
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
db:
image: postgres
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 10s
retries: 5
app:
image: myapp
depends_on:
db:
condition: service_healthy
web:
condition: service_healthy
# disable a healthcheck
debug:
image: nginx
healthcheck:
disable: trueBuenas prácticas de healthcheck
Comprueba un endpoint real /healthz que verifique las dependencias críticas (base de datos, caché) — una comprobación TCP simple puede pasar mientras la app está rota. Mantén las comprobaciones ligeras y rápidas; corren en cada intervalo. Usa start_period para runtimes de arranque lento (JVM, Rails) y que no se marquen como no saludables durante el arranque.
# check the actual app endpoint, not just TCP
HEALTHCHECK CMD curl -f http://localhost/healthz || exit 1
# include a /healthz endpoint in your app
# that verifies DB and cache connectivity
# keep checks fast (under timeout)
HEALTHCHECK --timeout=3s CMD curl -f http://localhost/healthz
# avoid heavy checks — they run every interval
# don't run migrations or full DB queries
# use start-period for slow starters (Java, Rails)
HEALTHCHECK --start-period=60s CMD ...
# for Swarm, health enables auto-restart of unhealthy tasks
# combine with restart policies and update_config
# example app endpoint (Express)
# app.get('/healthz', (req, res) => res.send('ok'))Límites de recursos
Límites de memoria
--memory fija un límite duro; superarlo dispara el OOM kill. --memory-swap acota memoria+swap combinadas; igualarlo a memory desactiva el swap. --memory-reservation es una sugerencia blanda para el kernel. Desactiva el swap para rendimiento predecible en cargas sensibles a la latencia.
# limit to 512MB of memory
docker run -d --memory="512m" nginx
# memory + swap (swap = memory + swap allowance)
docker run -d --memory="512m" --memory-swap="1g" nginx
# soft limit (hint to the kernel, may be exceeded)
docker run -d --memory-reservation="256m" nginx
# disable swap (swap = memory, no extra)
docker run -d --memory="512m" --memory-swap="512m" nginx
# OOM behavior: kill the container (default)
docker run -d --memory="512m" --oom-kill-disable nginx
# verify limits
docker inspect --format '{{.HostConfig.Memory}}' <container>Límites de CPU
--cpus fija el límite de CPU como fracción de núcleos (1.5 = 1.5 núcleos). --cpu-shares es un peso relativo usado en competencia, no un tope duro. --cpuset-cpus fija un contenedor a núcleos concretos, útil para el aislamiento de rendimiento. Quota/period es la forma de cgroup de bajo nivel.
# limit to 1 CPU (1.0 = one full core)
docker run -d --cpus="1.0" nginx
# limit to 1.5 CPUs
docker run -d --cpus="1.5" nginx
# CPU shares (relative weight, default 1024)
docker run -d --cpu-shares=512 nginx
# pin to specific CPU cores (0,1)
docker run -d --cpuset-cpus="0,1" nginx
# pin to cores 0-3
docker run -d --cpuset-cpus="0-3" nginx
# quota/period form (100000us per 100000us = 1 CPU)
docker run -d --cpu-quota=50000 --cpu-period=100000 nginxComportamiento de memoria y swap
memory-swap es el total de memoria + swap. Igualarlo a memory desactiva el swap. -1 permite swap ilimitado. Swappiness (0-100) controla la tendencia del kernel a hacer swap; valores menores favorecen mantener páginas en RAM. Los límites de memoria del kernel son avanzados y rara vez necesarios.
# memory limit, swap disabled
docker run -d -m 512m --memory-swap 512m nginx
# memory limit, 512m extra swap
docker run -d -m 512m --memory-swap 1g nginx
# unlimited swap (limited memory)
docker run -d -m 512m --memory-swap -1 nginx
# swappiness (0-100, lower = less swapping)
docker run -d -m 512m --memory-swappiness=10 nginx
# kernel memory limit (advanced, rarely needed)
docker run -d --kernel-memory="100m" nginx
# verify swap settings
docker inspect --format '{{.HostConfig.MemorySwap}}' <container>Límites de recursos en Compose
deploy.resources.limits fija topes duros; reservations fija garantías blandas (usadas para la programación). Swarm los respeta de forma nativa. Para Compose puro (sin Swarm), usa mem_limit y cpus de nivel superior en el formato v2. Las reservations permiten a un contenedor reclamar un mínimo incluso estando inactivo.
services:
web:
image: nginx
deploy:
resources:
limits:
cpus: "1.0"
memory: 512M
reservations:
cpus: "0.25"
memory: 256M
worker:
image: myworker
mem_swappiness: 10
memswap_limit: 1g
cpus: 2.0
# limits = hard caps; reservations = soft guarantees
# Swarm honors deploy.resources
# plain Compose: use top-level mem_limit, cpus (v2 compat)OOM y comportamiento de reinicio
Cuando la memoria se agota, el OOM-killer del kernel elige una víctima. oom-kill-disable protege a un contenedor pero puede tumbar al host — úsalo solo con límites de memoria del host. oom-score-adj sesga la selección: positivo = eliminado primero, negativo = protegido. Comprueba OOMKilled para diagnosticar reinicios.
# default: OOM kills the container, restart policy restarts it
docker run -d --memory=512m --restart unless-stopped nginx
# disable OOM kill for this container (risky)
docker run -d --memory=512m --oom-kill-disable nginx
# set OOM score adjustment (higher = killed first)
docker run -d --oom-score-adj=500 nginx
# protect a critical container (killed last)
docker run -d --oom-score-adj=-500 nginx
# verify restart count
docker inspect --format '{{.RestartCount}}' <container>
# check if OOM-killed
docker inspect --format '{{.State.OOMKilled}}' <container>Inspeccionar el uso de recursos
docker stats transmite en vivo la CPU, memoria, red e IO de disco por contenedor — la herramienta de referencia para un triage rápido. --no-stream da una única instantánea para scripts. Para análisis más profundo, scrapea /sys/fs/cgroup o expón métricas de Prometheus vía cAdvisor. Compara el uso contra los límites para dimensionar bien.
# live resource stats (CPU, memory, network, IO)
docker stats
# specific container
docker stats web
# one snapshot (no streaming)
docker stats --no-stream
# custom format
docker stats --format "table {{.Name}} {{.CPUPerc}} {{.MemUsage}}"
# container cgroup details
docker exec web cat /sys/fs/cgroup/memory/memory.usage_in_bytes
docker exec web cat /sys/fs/cgroup/cpu/cpu.stat
# inspect configured limits
docker inspect --format '{{.HostConfig.Memory}} {{.HostConfig.NanoCpus}}' webSeguridad
Usuario non-root
Ejecutar como non-root limita el radio de impacto si la app se ve comprometida. Crea un usuario dedicado en el Dockerfile y cámbiate a él con USER. Si debes enlazar un puerto privilegiado, usa un proxy inverso (nginx) o concede la capability NET_BIND_SERVICE en lugar de ejecutar como root.
# Dockerfile: create and use a non-root user
FROM node:20-alpine
RUN addgroup -S app && adduser -S app -G app
USER app
WORKDIR /app
COPY --chown=app:app . .
CMD ["node", "server.js"]
# at runtime, override the user
docker run -u 1000:1000 myapp
# verify the current user
docker exec web id
# bind to privileged ports? Use capabilities or a reverse proxy
# non-root cannot bind to ports < 1024 without NET_BIND_SERVICE
# distroless images ship a non-root user by default
FROM gcr.io/distroless/nodejs20
USER nonrootSistema de archivos raíz de solo lectura
Un sistema de archivos raíz de solo lectura impide que atacantes escriban malware o modifiquen configuraciones si se ven comprometidos. Emparéjalo con tmpfs para directorios temporales (/tmp, /cache) y volúmenes para datos persistentes. Las apps deben estar diseñadas para esto — algunos frameworks escriben en rutas inesperadas y necesitan montajes tmpfs.
# make the root filesystem read-only
docker run --read-only nginx
# allow writes only to specific dirs via tmpfs
docker run --read-only --tmpfs /tmp --tmpfs /var/cache nginx
# combine with a writable volume for persistent data
docker run --read-only -v appdata:/data --tmpfs /tmp myapp
# compose form
services:
web:
image: nginx
read_only: true
tmpfs:
- /tmp
- /var/cache/nginx
# apps must be designed to not write outside allowed pathsCapabilities de Linux
Por defecto Docker concede un conjunto limitado de capabilities de Linux. Elimina ALL y añade de vuelta solo lo que la app necesita — el principio de mínimo privilegio. --privileged concede todas las capabilities y acceso a dispositivos del host; evítalo por completo salvo para runtimes de contenedores de confianza. Elimina NET_RAW por defecto.
# drop all capabilities, add only what's needed
docker run --cap-drop=ALL --cap-add=NET_BIND_SERVICE nginx
# add a specific capability
docker run --cap-add=SYS_PTRACE myapp
# common capabilities to drop (rarely needed by apps)
# CHOWN, DAC_OVERRIDE, FOWNER, KILL, NET_RAW, SETGID, SETUID
# NET_RAW is often safe to drop (prevents raw sockets/ping)
docker run --cap-drop=NET_RAW myapp
# privileged = all capabilities + host access (AVOID)
docker run --privileged myapp # DANGEROUS
# inspect capabilities
docker inspect --format '{{json .HostConfig.CapAdd}}' <container>Seccomp y AppArmor
Seccomp filtra qué syscalls puede hacer un contenedor — el perfil por defecto bloquea ~44 syscalls peligrosas. AppArmor confina el acceso a archivos y capabilities. no-new-privileges impide que binarios setuid concedan nuevos privilegios — un endurecimiento barato y de alto valor para cualquier contenedor.
# default seccomp profile blocks dangerous syscalls
docker run --security-opt seccomp=default.json nginx
# custom seccomp profile
docker run --security-opt seccomp=/path/to/profile.json nginx
# disable seccomp (NOT recommended)
docker run --security-opt seccomp=unconfined nginx
# AppArmor profile
docker run --security-opt apparmor=docker-default nginx
# custom AppArmor profile
docker run --security-opt apparmor=myprofile nginx
# no-new-privileges (prevents setuid escalation)
docker run --security-opt no-new-privileges nginxEscaneo de imágenes
Escanea las imágenes buscando vulnerabilidades conocidas (CVEs) antes de publicar. docker scout (antes docker scan basado en snyk) viene integrado. Trivy y Grype son alternativas populares. Integra el escaneo en CI para bloquear imágenes con CVEs de gravedad alta. Vuelve a escanear las imágenes base periódicamente a medida que se divulgan nuevos CVEs.
# docker scout (built-in, replaces docker scan)
docker scout cves myapp:1.0
# scan a local image
docker scout cves --format json myapp:1.0
# compare two images
docker scout compare myapp:1.0 --to myapp:1.1
# Trivy (third-party, popular)
trivy image myapp:1.0
# Grype (third-party)
grype myapp:1.0
# scan a Dockerfile for bad practices
docker scout policy myapp --only-stream-default
# integrate scanning in CI
# - build image
# - scan
# - fail the pipeline on HIGH/CRITICAL CVEsContent Trust y endurecimiento
Content Trust garantiza que descargas imágenes firmadas. Endurece el daemon: desactiva la comunicación entre contenedores (icc=false), habilita live-restore para que los contenedores sobrevivan a reinicios del daemon, y habilita los user namespaces (userns-remap) para mapear el root del contenedor a un UID del host non-root y lograr un aislamiento más fuerte.
# enable content trust (image signing)
export DOCKER_CONTENT_TRUST=1
docker pull myapp:1.0 # refuses unsigned
# sign on push
docker push myapp:1.0 # signs with your key
# daemon hardening in /etc/docker/daemon.json
# {
# "userland-proxy": false,
# "live-restore": true,
# "no-new-privileges": true,
# "icc": false # disable inter-container communication on default bridge
# }
# restrict registry access
# "registry-mirrors": [],
# "insecure-registries": []
# audit the daemon
docker info --format '{{json .SecurityOptions}}'
# use user namespaces for host UID isolation
# /etc/docker/daemon.json: "userns-remap": "default"Logging y monitoreo
Ver logs
docker logs lee el stdout/stderr capturado por el driver de logging. Las apps deberían escribir logs en stdout — no en archivos — para integrarse con docker logs. --tail y --since limitan la salida. compose logs agrega entre servicios. El driver json-file por defecto crece sin límite si no lo acotas.
# follow logs
docker logs -f web
# last 100 lines
docker logs --tail 100 web
# since a timestamp
docker logs --since 30m web
# with timestamps
docker logs -t web
# a specific time range
docker logs --since 1h --until 30m web
# write logs to a file
docker logs web > web.log 2>&1
# logs for all containers (compose)
docker compose logs -f
docker compose logs -f web dbDrivers de log
El driver json-file crece sin límite sin rotación — fija max-size y max-file para evitar el agotamiento del disco. En producción, envía los logs a un sistema central (fluentd, splunk, awslogs, gelf). Fija un valor por defecto global en daemon.json para que cada contenedor tenga rotación por defecto.
# default: json-file
docker run -d --log-driver=json-file nginx
# cap log size and rotate (json-file)
docker run -d \
--log-driver=json-file \
--log-opt max-size=10m \
--log-opt max-file=3 \
nginx
# syslog
docker run -d --log-driver=syslog nginx
# journald
docker run -d --log-driver=journald nginx
# fluentd / splunk / gelf / awslogs
docker run -d --log-driver=fluentd nginx
# global default in /etc/docker/daemon.json
# { "log-driver": "json-file",
# "log-opts": { "max-size": "10m", "max-file": "3" } }Etiquetado y atributos de logs
La plantilla tag personaliza los identificadores de log — usar {{.Name}} produce nombres de contenedor legibles en lugar de IDs truncados. Para fluentd/splunk, las labels y las variables de env se adjuntan a los registros de log para filtrar. Fija plantillas de tag a nivel de daemon para que todos los contenedores se etiqueten consistentemente.
# tag logs with container name instead of ID
docker run -d \
--log-driver=json-file \
--log-opt tag="{{.Name}}" \
nginx
# tag with image name and tag
--log-opt tag="{{.ImageName}}/{{.Name}}"
# fluentd: add labels and attributes
docker run -d \
--log-driver=fluentd \
--log-opt fluentd-address=localhost:24224 \
--log-opt tag="docker.{{.Name}}" \
--log-opt labels=app,env \
--label app=web --label env=prod \
nginx
# syslog with facility
docker run -d --log-driver=syslog \
--log-opt syslog-facility=daemon nginxStats y monitoreo de recursos
stats transmite CPU, memoria, red e IO de bloque. docker events es un flujo en tiempo real de eventos del daemon — útil para scripts de alertas. docker top muestra los procesos dentro de un contenedor; docker diff muestra los cambios del sistema de archivos (A=añadido, C=cambiado, D=eliminado) desde que se creó la imagen.
# live stats for all containers
docker stats
# specific container, one snapshot
docker stats --no-stream web
# custom format
docker stats --format "table {{.Name}} {{.CPUPerc}} {{.MemUsage}} {{.NetIO}}"
# events stream (start, stop, die, etc.)
docker events
# filter events
docker events --filter type=container --filter event=die
# container process list (like top)
docker top web
# container file changes since creation
docker diff webDocker events
docker events es un flujo en tiempo real de eventos del ciclo de vida: create, start, stop, pause, die, destroy, más eventos de imagen y red. Filtra por type, event o contenedor. Es la base de los scripts de alerta que reaccionan a muertes de contenedores o reinician automáticamente servicios que fallan.
# stream all events
docker events
# container events only
docker events --filter type=container
# specific event types
docker events --filter event=start --filter event=die
# events for a specific container
docker events --filter container=web
# events since a timestamp
docker events --since 1h
# format output
docker events --format '{{.Time}} {{.Action}} {{.Actor.Attributes.name}}'
# pipe to a monitoring script
docker events --filter event=die | while read event; do
echo "Container died: $event"
doneStack Prometheus y Grafana
cAdvisor expone métricas por contenedor (CPU, memoria, red, sistema de archivos) en formato Prometheus. Prometheus las scrapea y las almacena; Grafana las visualiza. Este es el stack de monitoreo open source de facto para Docker. Añade node-exporter para métricas del host y alertmanager para alertas.
# run cAdvisor (container metrics exporter)
docker run -d --name cadvisor \
-v /:/rootfs:ro -v /var/run:/var/run:ro \
-v /sys:/sys:ro -v /var/lib/docker/:/var/lib/docker:ro \
-p 8080:8080 gcr.io/cadvisor/cadvisor
# run Prometheus
docker run -d -p 9090:9090 \
-v ./prometheus.yml:/etc/prometheus/prometheus.yml \
prom/prometheus
# run Grafana
docker run -d -p 3000:3000 grafana/grafana
# scrape cAdvisor in prometheus.yml
# scrape_configs:
# - job_name: cadvisor
# static_configs:
# - targets: ['cadvisor:8080']
# view dashboards in Grafana at http://localhost:3000Docker Swarm
Inicializar Swarm
swarm init convierte un host Docker en un manager de Swarm. El token de join permite que workers y managers adicionales se unan. Mantén los tokens de manager en secreto — pueden controlar el clúster. Ejecuta un número impar de managers (3 o 5) para la tolerancia del consenso Raft. Los workers ejecutan tareas; los managers las programan.
# initialize a Swarm (this node becomes a manager)
docker swarm init --advertise-addr 10.0.0.5
# get a join token for workers
docker swarm join-token worker
# get a join token for managers
docker swarm join-token manager
# on a worker node
docker swarm join --token SWMTKN-... 10.0.0.5:2377
# list nodes
docker node ls
# promote a worker to manager
docker node promote <node>
# demote a manager
docker node demote <node>
# leave the Swarm (worker)
docker swarm leaveDesplegar servicios
Los servicios son la abstracción de Swarm sobre los contenedores. Un servicio replicado ejecuta N tareas idénticas; un servicio global ejecuta una tarea por nodo. update despliega una imagen nueva con cero tiempo de inactividad por defecto. scale cambia el número de réplicas en vivo. Swarm reprograma si un nodo falla.
# deploy a service
docker service create --name web -p 80:80 nginx
# with replicas
docker service create --name web --replicas 3 -p 80:80 nginx
# with a constraint (e.g. only on worker nodes)
docker service create --name web --replicas 3 \
--constraint node.role==worker nginx
# with a global service (one per node)
docker service create --name log --mode global fluentd
# update the image
docker service update --image nginx:1.25 web
# scale a service
docker service scale web=5
# remove a service
docker service rm webEscalado y actualizaciones
scale cambia el número de réplicas al instante. update realiza actualizaciones en cascada — parallelism controla cuántas tareas se actualizan a la vez, delay las espacia, y failure-action=rollback revierte automáticamente ante errores. Swarm mantiene las tareas antiguas corriendo hasta que las nuevas estén saludables, habilitando despliegues con cero tiempo de inactividad.
# scale up
docker service scale web=10
# scale multiple services
docker service scale web=5 worker=8
# rolling update
docker service update --image myapp:2.0 web
# update with parallelism and delay
docker service update \
--image myapp:2.0 \
--update-parallelism 2 \
--update-delay 30s \
--update-failure-action rollback \
web
# environment or port update without redeploy
docker service update --env-add DEBUG=true web
docker service update --publish-rm 80:80 --publish-add 8080:80 web
# rollback to previous version
docker service rollback webDespliegue de stacks
Un stack es un archivo Compose desplegado en Swarm. La clave deploy: configura réplicas, políticas de update/rollback, restricciones de colocación y recursos — elementos específicos de Swarm. docker stack deploy aplica la especificación de forma declarativa. Los stacks agrupan servicios, redes y secretos relacionados.
# docker-compose.yml as a Swarm stack
docker stack deploy -c docker-compose.yml mystack
# the compose file uses deploy: for Swarm config
services:
web:
image: nginx
deploy:
replicas: 3
update_config:
parallelism: 1
delay: 10s
restart_policy:
condition: on-failure
placement:
constraints: [node.role == worker]
ports:
- "80:80"
# list stacks and services
docker stack ls
docker stack services mystack
# remove a stack
docker stack rm mystackGestión de nodos
Drena (drain) un nodo antes del mantenimiento para reprogramar con elegancia sus tareas en otro lugar. Active/pause/drain controlan la programación. Las labels habilitan restricciones de colocación (por ejemplo, ejecutar la base de datos solo en nodos etiquetados tier=db). Elimina un nodo solo después de que haya salido del Swarm con docker swarm leave.
# list nodes
docker node ls
# node details (status, role, labels, resources)
docker node inspect <node>
# drain a node (reschedule tasks off it, for maintenance)
docker node update --availability drain <node>
# activate a drained node
docker node update --availability active <node>
# pause a node (no new tasks, existing stay)
docker node update --availability pause <node>
# add a label (for placement constraints)
docker node update --label-add tier=db <node>
# remove a node from the Swarm
docker node rm <node>
# (node must have left via 'docker swarm leave' first)Secrets y configs
Los secretos están cifrados en reposo y en tránsito, se montan como archivos bajo /run/secrets y nunca se escriben en capas de imagen ni variables de entorno. Son inmutables — para rotar, crea un secreto nuevo y actualiza el servicio. Los configs son similares pero para datos no sensibles como archivos de configuración. Ambos son exclusivos de Swarm.
# create a secret from a file
docker secret create db_password ./db_password.txt
# create from stdin
echo "supersecret" | docker secret create db_password -
# use in a service
docker service create --name app --secret db_password myapp
# read in the app
# cat /run/secrets/db_password
# update a secret (immutable — create a new one)
echo "newsecret" | docker secret create db_password_v2 -
docker service update --secret-rm db_password --secret-add source=db_password_v2 app
# configs (non-sensitive, e.g. nginx.conf)
echo "server {...}" | docker config create nginx_conf -
docker service create --config nginx_conf nginx
# list and remove
docker secret ls
docker config lsFragmentos de Docker relacionados
Copy-paste ready code for common tasks.
Run a Container
Run, list, stop, and remove Docker containers.
Writing a Dockerfile
Build an image from a Dockerfile with multi-instruction layers.
Image Management
Pull, list, tag, push, and prune images.
Volumes & Bind Mounts
Persist data with named volumes, anonymous volumes, and bind mounts.
Networking
Create networks, attach containers, and expose ports.
Docker Compose
Define and run multi-container apps with compose.
Multi-Stage Build
Build artifacts in one stage and copy them into a slim final image.
Exec & Logs
Run commands inside running containers and inspect logs.
Was this helpful?