Skip to content

Docker Шпаргалка

Платформа для разработки, доставки и запуска приложений в контейнерах.

01

Начало работы

Базовые команды

docker run создаёт и запускает контейнер. -d запускает в фоне, -p сопоставляет порт хоста с портом контейнера. pull скачивает образы из registry (по умолчанию Docker Hub).

docker
# 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 images

Жизненный цикл контейнера

create + start — это то, что run делает внутри. stop отправляет SIGTERM для корректной остановки; kill сразу отправляет SIGKILL. pause использует cgroup freezer — удобно для снятия состояния, не останавливая процесс.

docker
# 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 web

Основы образов

Образы состоят из слоёв только для чтения. rmi завершится ошибкой, если на образ всё ещё ссылается контейнер, — сначала удалите контейнер. history показывает каждую инструкцию, создавшую слой, и его размер — полезно для оптимизации сборки.

docker
# 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:latest

Информация о системе

docker info показывает конфигурацию демона: storage driver, runtime, registry, статус swarm. system df показывает, сколько места можно освободить: висячие образы и остановленные контейнеры зря занимают диск. Флаг --format использует Go-шаблоны для структурированного вывода.

docker
# 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}}'

Очистка и prune

prune безопасно удаляет остановленные и висячие ресурсы. system prune -a дополнительно удаляет образы, на которые не ссылается ни один контейнер. Флаг --volumes удаляет тома, не используемые контейнерами, — это необратимая потеря данных, применяйте осторожно в production.

docker
# 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 --volumes

Получение справки

Docker группирует команды в пространства управления (docker image, docker container, docker network, docker volume). Работают и старые (docker rmi), и новые (docker image rm) формы. --help у любой подкоманды показывает флаги и примеры использования.

docker
# 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/
02

Управление образами

Загрузка образов

Теги — изменяемые метки: один и тот же тег со временем может указывать на разные образы. Для воспроизводимых деплоев фиксируйте образ по digest (@sha256:...). Загрузка с --platform позволяет получить образ для другой архитектуры — полезно для сборок ARM на x86-хостах.

docker
# 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 nginx

Сборка образов

Последняя точка — это контекст сборки: файлы, отправляемые демону. Держите его маленьким с помощью .dockerignore, чтобы ускорить сборку. --no-cache принудительно пересобирает слои при отладке. BuildKit включает кеширование многоступенчатых сборок, SSH-монтирования и монтирование секретов.

docker
# 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 .

Тегирование образов

Теги — это псевдонимы, указывающие на один и тот же ID образа. Обычный workflow: собрать образ с версионным тегом, затем добавить теги latest и major-версии. Тег с URL registry подготавливает образ к push в этот registry.

docker
# 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:pinned

Публикация образов

Перед push образ нужно пометить тегом с адресом registry. push загружает только те слои, которых ещё нет в registry. Для приватных registry с самоподписанными сертификатами настройте демон в /etc/docker/daemon.json через insecure-registries.

docker
# 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 logout

Инспекция образов

inspect возвращает подробный JSON: архитектуру, ОС, слои, env, entrypoint, конфигурацию. history раскрывает команду и размер каждого слоя — основа оптимизации образов. manifest inspect проверяет удалённый registry без загрузки образа.

docker
# 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:latest

Сохранение и загрузка образов

save/load сохраняет слои и историю образа — правильный выбор для переноса образов офлайн. export/import сплющивает образ в один слой и теряет историю. Для передачи по сети предпочитайте push/pull в registry, а не tar-файлы.

docker
# 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.gz
03

Управление контейнерами

Запуск контейнеров

-it объединяет -i (держать stdin открытым) и -t (выделить tty) для интерактивных сессий. --rm удаляет контейнер после выхода — идеально для разовых команд. --restart unless-stopped переживает перезагрузки, но уважает ручную остановку.

docker
# 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 nginx

Выполнение команд (exec)

exec запускает новый процесс внутри уже работающего контейнера — исходный entrypoint продолжает работать. Используйте его для отладки, административных задач и разовых скриптов. По умолчанию используется USER образа; переопределите через -u.

docker
# 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/marker

Просмотр логов

logs показывает stdout/stderr, захваченный logging driver контейнера. Приложения должны писать в stdout, а не в файлы, чтобы интегрироваться с docker logs. --since/--until принимают метки времени RFC3339 или длительности Go (30m, 2h).

docker
# 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 web

Инспекция контейнера

inspect возвращает богатый JSON с конфигурацией, состоянием, сетью и монтированиями. Go-шаблоны извлекают отдельные поля — крайне полезно для скриптов. LogPath показывает, где драйвер json-file хранит логи на хосте.

docker
# 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}}' web

Запуск, остановка и перезапуск

start возобновляет остановленный контейнер с его исходной конфигурацией. update изменяет ограничения и политику перезапуска работающего контейнера без пересоздания — удобно для ужесточения лимитов в production.

docker
# 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 web

Копирование файлов

cp работает в обе стороны и с остановленными контейнерами — удобно для срочных исправлений и вытаскивания логов. Он не рассчитан на частую синхронизацию; для разработки используйте bind mount или том. Приём tar+exec эффективно передаёт большие деревья файлов.

docker
# 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.gz
04

Основы Dockerfile

FROM — базовый образ

FROM — первая инструкция, задающая базовый слой. Выбирайте минимальные базы (alpine, distroless, scratch), чтобы уменьшить поверхность атаки и размер. Фиксация по digest гарантирует воспроизводимость сборки, так как теги могут меняться.

docker
# 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 final

RUN — выполнение команд

Каждый RUN создаёт слой. Объединяйте связанные команды через && и очищайте всё в том же слое, чтобы образ оставался маленьким. Exec-форма (JSON-массив) не вызывает shell, поэтому нет подстановки переменных и цепочек команд, зато сигналы обрабатываются правильно.

docker
# 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.gz

COPY и ADD

Для локальных файлов предпочитайте COPY — он явный и предсказуемый. ADD добавляет магию: скачивание по URL и автоматическую распаковку tar/zip. Эта магия может удивить; используйте ADD только когда нужна распаковка. Обе инструкции создают слой.

docker
# 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 задаёт рабочий каталог для последующих инструкций и по умолчанию для контейнера. Если каталога нет, он создаётся. Всегда предпочитайте WORKDIR вместо cd в RUN — cd не сохраняется между слоями. Для ясности используйте абсолютные пути.

docker
# 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 RUN

USER

USER задаёт пользователя (и при необходимости группу) для RUN, CMD и ENTRYPOINT. Запуск не от root — ключевая практика безопасности. Пользователь должен существовать в образе. Числовые UID переносимы между образами и избавляют от проблем с поиском имени.

docker
# 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 уменьшает контекст сборки, отправляемый демону: сборка быстрее, контекст меньше, а секреты вроде .env не попадут в слои образа. Синтаксис похож на .gitignore. Всегда исключайте node_modules и артефакты сборки, которые пересоздаются при сборке.

docker
# .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.db
05

Продвинутый Dockerfile

CMD против ENTRYPOINT

ENTRYPOINT задаёт исполняемый файл; CMD — аргументы по умолчанию, которые можно переопределить. Используйте exec-форму (JSON-массив), чтобы процесс получал сигналы напрямую: shell-форма оборачивает команду в /bin/sh -c и ломает корректную остановку. Частый приём: ENTRYPOINT-скрипт + аргументы по умолчанию в CMD.

docker
# 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 — переменные окружения

ENV создаёт переменные уровня образа, видимые при сборке и в runtime. Для значений, нужных только при сборке, используйте ARG, чтобы не тащить конфигурацию в финальный образ. В exec-форме CMD/ENTRYPOINT ${VAR} не раскрывается shell — оберните в sh -c.

docker
# 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 — аргументы сборки

Значения ARG существуют только во время сборки той стадии, где они объявлены. В runtime-контейнер они не попадают — чтобы передать значение дальше, используйте ENV. ARG, объявленные до FROM, «глобальны», но в каждой стадии их нужно объявить заново, чтобы использовать.

docker
# 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 — это документация, он не публикует порты. Публикация происходит через -p (host:container) в runtime или ports: в Compose. EXPOSE помогает инструментам понять предполагаемые порты и включает автоматическое связывание в устаревших сетях.

docker
# 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}}' myapp

LABEL и метаданные

LABEL прикрепляет к образу метаданные в виде ключ-значение. Используйте метки OCI org.opencontainers.image.* для совместимости с registry и инструментами. Метки удобны для отслеживания версии, источника, лицензии и информации о сборке CI.

docker
# 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 в Dockerfile

VOLUME объявляет точку монтирования; при первом запуске Docker создаёт анонимный том, если вы не смонтировали путь хоста. Это сигнал, что каталог хранит состояние. Подводный камень: объявление VOLUME после COPY может перекрыть скопированные файлы пустым томом.

docker
# 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 /config
06

Многоступенчатые сборки

Базовая многоступенчатая сборка

Многоступенчатые сборки копируют в runtime-образ только финальные артефакты — инструменты сборки, исходники и dev-зависимости остаются в стадии builder. Результат: крошечный и безопасный runtime-образ. Называйте стадии через AS, чтобы ссылаться на них в COPY --from.

docker
# 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;"]

Выбор стадии сборки

--target собирает только до указанной стадии, пропуская последующие. Это позволяет держать один Dockerfile для dev, test и production: цель test для CI, final для production. BuildKit автоматически распараллеливает независимые стадии.

docker
# 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 .

Тонкие runtime-образы

Для статических бинарников (Go, Rust) scratch даёт минимально возможный образ с нулевой поверхностью атаки. Добавьте CA-сертификаты для HTTPS. Distroless предлагает минимальную базу с корневыми CA и пользователем не-root — идеально для динамических языков или когда нужен runtime без shell.

docker
# 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"]

Паттерн builder для компилируемых языков

Компилируйте в полном образе SDK, затем копируйте артефакт в образ только для runtime (JRE). Это резко уменьшает размер (JDK ~600 МБ против JRE ~200 МБ) и убирает инструменты сборки из production. Предварительная загрузка зависимостей до COPY улучшает кеширование слоёв.

docker
# 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 runtime

Копирование из внешних образов

COPY --from может брать файлы из любого образа — удобно, чтобы собрать инструменты из разных баз без стадии сборки. На стадии можно ссылаться и по индексу (с нуля), но именование через AS понятнее. Фиксируйте внешние образы по digest для воспроизводимости.

docker
# 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 /app

Возможности BuildKit

BuildKit открывает кеш-монтирования (кеши npm/pip сохраняются между сборками, не раздувая образ), монтирование секретов (учётные данные никогда не попадают в слой), проброс SSH для приватных репозиториев и синтаксис heredoc для аккуратных многострочных RUN. Добавьте директиву # syntax, чтобы зафиксировать версию frontend Dockerfile.

docker
# 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
EOF
07

Тома

Создание и использование томов

Именованные тома управляются Docker — это рекомендуемый способ хранить данные. Они переживают удаление контейнера и не зависят от структуры файловой системы хоста. Суффикс :ro монтирует том только для чтения. inspect показывает путь на диске в /var/lib/docker/volumes.

docker
# 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 mydata

Список и инспекция томов

ls перечисляет именованные тома; inspect показывает драйвер и точку монтирования. Чтобы узнать, какие контейнеры используют том, отфильтруйте ps по тому. На Linux тома лежат в /var/lib/docker/volumes/<name>/_data — обращайтесь через docker exec, а не правьте файлы с хоста.

docker
# 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 mydata

Драйверы томов

Драйвер local поддерживает NFS, блочные устройства и tmpfs через опции монтирования. Для облачного хранилища (EBS, Azure Disk) используйте плагин-драйвер. Драйверы абстрагируют хранилище, поэтому контейнеры переносятся между хостами без изменения команды запуска — это важно для Swarm/Kubernetes.

docker
# 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 ebsvol

Резервное копирование томов

Сделайте бэкап тома, смонтировав в временный контейнер и том, и каталог хоста, затем упакуйте содержимое в tar. Восстановление повторяет процесс в обратном порядке. Этот приём работает с любым драйвером томов и лежит в основе скриптов автоматического бэкапа.

docker
# 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 /data

Удаление томов

Том нельзя удалить, пока на него ссылается контейнер (сначала удалите контейнер). prune удаляет только неиспользуемые тома. Удаление тома необратимо — данные теряются навсегда. Всегда делайте бэкап production-томов перед prune.

docker
# 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 mydata

Общие тома между контейнерами

Несколько контейнеров могут монтировать один том, чтобы разделять состояние. --volumes-from копирует монтирования томов другого контейнера — удобно для sidecar-паттернов. Добавьте :ro для потребителей только на чтение. Согласуйте конкурентную запись, чтобы избежать повреждения данных; некоторым приложениям нужна блокировка.

docker
# 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/msg
08

Bind-монтирования

Базовое bind-монтирование

Bind-монтирования напрямую отображают путь хоста в контейнер — идеально для живой разработки, когда правки на хосте видны сразу. Используйте абсолютные пути хоста. Суффикс :ro запрещает контейнеру писать обратно на хост. Современный синтаксис использует --mount для наглядности.

docker
# 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:/app

Bind-монтирование только для чтения

Монтирования только для чтения защищают конфигурацию хоста от записи из контейнера — критично для безопасности. --read-only делает всю корневую файловую систему неизменяемой, требуя явных записываемых монтирований для /tmp и каталогов логов. Это укрепляет контейнеры против компрометации.

docker
# 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 fail

Workflow разработки

Смонтируйте исходный код, чтобы правки на хосте сразу отражались в контейнере. Приём с анонимным томом для node_modules не даёт пустому node_modules хоста перекрыть зависимости, установленные в образе. На Windows/Mac может потребоваться polling для надёжного отслеживания файлов.

docker
# 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 start

Метки SELinux и AppArmor

На хостах с SELinux (RHEL/CentOS/Fedora) bind-монтированиям нужен суффикс :z или :Z, чтобы перемаркировать путь хоста и дать контейнеру доступ. :z делает путь общим для контейнеров, :Z — приватным. Забытый суффикс приводит к ошибкам permission denied.

docker
# 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 myapp

Mount, volume и tmpfs

Тома: управляются Docker, переносимы, лучший выбор для постоянных данных. Bind-монтирования: пути хоста, лучший выбор для разработки и подстановки конфигурации. tmpfs: в памяти, лучший выбор для секретов и эфемерных кешей. Синтаксис --mount явнее и понятнее, чем -v.

docker
# 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 nginx

Bind-монтирования в Compose

В Compose относительный путь (./html) создаёт bind-монтирование, а имя (logs), указанное в разделе volumes:, создаёт именованный том. Голый путь (/cache) создаёт анонимный том. Длинный синтаксис делает опции вроде read_only явными.

docker
# 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: true
09

Сети

Bridge-сеть (по умолчанию)

В стандартной bridge-сети нет автоматического DNS — контейнеры должны использовать IP. Пользовательские bridge-сети дают service discovery через DNS: контейнеры находят друг друга по имени. Поэтому Compose автоматически создаёт отдельную сеть для каждого проекта.

docker
# 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 apps

Сеть host

Сеть host убирает сетевой namespace — контейнер использует интерфейсы и порты хоста. Это максимальная производительность, но ценой изоляции и проброса портов. Доступно только на Linux; на Mac/Windows это сеть виртуальной машины, а не хоста.

docker
# 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 myapp

Overlay-сеть (Swarm)

Overlay-сети охватывают несколько узлов Swarm, обеспечивая безопасную межхостовую связь со встроенным DNS. --attachable позволяет обычным контейнерам подключаться к overlay (полезно для отладки). Шифрование защищает трафик между узлами — включайте его для чувствительных нагрузок.

docker
# 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 container

Пользовательские сети

Пользовательские сети дают контроль над подсетями, шлюзами и изоляцией. --internal блокирует доступ в интернет. macvlan даёт контейнерам реальное присутствие в физической LAN (у каждого свой MAC) — полезно для устаревших приложений, но по умолчанию ломает связь хост-контейнер.

docker
# 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 mymacvlan

DNS контейнеров

Встроенный DNS Docker (127.0.0.11) разрешает имена контейнеров в пользовательских сетях. В стандартной bridge-сети DNS нет. --dns добавляет внешние резолверы; --add-host вставляет статические записи. Используйте имена сервисов, а не IP, чтобы передеплой не ломал связь.

docker
# 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"

Инспекция и управление сетями

network connect/disconnect подключает работающий контейнер к дополнительным сетям без перезапуска — удобно для sidecar. inspect показывает подключённые контейнеры, подсеть и драйвер. prune удаляет сети, не используемые ни одним контейнером.

docker
# 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 prune
10

Проброс портов

Базовый проброс портов

-p host:container сопоставляет порт хоста порту контейнера. Если порт хоста опущен, Docker выбирает случайный (узнать его можно через docker port). Каждый порт хоста может указывать только на один контейнер — для нескольких экземпляров используйте reverse proxy или разные порты хоста.

docker
# 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 nginx

Привязка к конкретному IP

IP в начале задаёт интерфейс, к которому привязывается порт. 127.0.0.1 оставляет сервис доступным только локально — обязательно для баз данных, которые не должны быть снаружи. 0.0.0.0 (по умолчанию) слушает все интерфейсы. В production всегда привязывайте базы к localhost.

docker
# 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"

Порты UDP и SCTP

Суффикс /udp или /sctp выбирает протокол; по умолчанию TCP. Для сервисов вроде DNS, которым нужны оба, объявите оба проброса. Диапазоны портов сопоставляются один к одному между хостом и контейнером — полезно для WebRTC, RTP или пассивного FTP. Убедитесь, что правила firewall соответствуют протоколам.

docker
# 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"

Диапазон портов

Диапазоны портов сопоставляются один к одному (хост 8000-8005 в контейнер 8000-8005). -P (заглавная) автоматически публикует каждый порт из EXPOSE на случайный высокий порт хоста — удобно для быстрых тестов. Если порты случайны, смотрите фактические сопоставления в docker ps.

docker
# 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}}'

Expose против publish

EXPOSE документирует намерение; -p реально публикует порт. В Compose expose открывает порт только другим сервисам в той же сети, а ports публикует его на хост. Разница важна для баз данных: expose внутри, никогда не публикуйте на хост в production.

docker
# 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}}' nginx

Случайный проброс портов

Если не указать порт хоста, Docker выберет случайный эфемерный порт (по умолчанию 32768-60999). Узнать его можно через docker port или docker ps. Это удобно для масштабирования одинаковых сервисов на одном хосте. Диапазон эфемерных портов настраивается в /proc/sys/net/ipv4/ip_local_port_range на Linux.

docker
# 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 80
11

Переменные окружения

Установка переменных окружения

-e (или --env) задаёт переменные окружения в контейнере. -e VAR без значения наследует переменную из shell хоста. Для чувствительных значений предпочитайте --env-file или Docker secrets, а не обычный -e, который виден в docker inspect и списке процессов.

docker
# 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 mysql

Файлы окружения

--env-file загружает переменные из файла, оставляя команду запуска чистой, а секреты — вне истории shell. Compose автоматически загружает .env верхнего уровня для подстановки в сам файл compose. Комментарии (#) и пустые строки игнорируются; кавычки сохраняются буквально.

docker
# .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 myapp

Переменные в Dockerfile

ENV «запекает» переменные в образ, они видны при сборке и в runtime. ARG существует только при сборке — преобразуйте его в ENV, если значение нужно в runtime. Запечённые значения можно переопределить через -e при запуске. Помните: переменные видны в docker inspect, не храните там секреты.

docker
# 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=true

Динамические переменные и подстановка

Раскрытие shell ($(...) или ${VAR}) происходит на хосте до того, как Docker увидит значение. В Compose ${VAR} подставляется из файла .env. В exec-форме CMD ${VAR} НЕ раскрывается — оберните команду в sh -c. Передавайте UID хоста для правильного владельца файлов в bind-монтированиях.

docker
# 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}"]

Environment в Compose

Поле environment в Compose принимает синтаксис списка или словаря. env_file загружает значения в контейнер; .env верхнего уровня даёт переменные для подстановки ${} в сам файл compose. При большом числе переменных используйте форму словаря — так читаемее.

docker
# 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=mydb

Управление секретами

Секреты монтируются как файлы в /run/secrets, никогда не как переменные окружения, и шифруются при передаче и хранении в Swarm. Не запекайте секреты в образ (ENV) и не передавайте через -e — и то и другое утекает через docker inspect и слои образа. Монтирование секретов BuildKit держит учётные данные сборки вне слоёв.

docker
# 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 recommended
12

Основы Docker Compose

Базовый docker-compose.yml

Compose описывает многоконтейнерное приложение в одном YAML-файле. services описывает контейнеры; volumes и networks объявляются на верхнем уровне. depends_on управляет порядком запуска. docker compose up -d запускает всё в фоне.

docker
# 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 -d

Команды Compose

up создаёт и запускает, down останавливает и удаляет. Добавьте -v к down, чтобы удалить тома (потеря данных). exec выполняет команду в работающем сервисе; run запускает новый контейнер для разовой задачи. --scale поднимает несколько реплик сервиса на одном хосте.

docker
# 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 migrate

Зависимости сервисов

depends_on управляет порядком запуска, но зависимость может быть ещё не готова — используйте condition: service_healthy с healthcheck, чтобы дождаться, пока база начнёт принимать соединения. service_completed_successfully ждёт завершения init-контейнеров. Приложение всё равно должно повторять подключение.

docker
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_successfully

Сборка в Compose

build описывает, как собрать образ из исходников; image задаёт тег результата. context отправляется сборщику (держите его маленьким). target выбирает стадию многоступенчатой сборки. --build принудительно пересобирает при up. Build args передают значения во время сборки.

docker
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 --build

Тома в Compose

Относительный путь (./html) — это bind-монтирование; имя (logs), объявленное в разделе volumes: верхнего уровня, — именованный том; голый путь (/cache) — анонимный том. Для именованных томов можно задать драйвер и опции (например, NFS). Compose добавляет к именам томов префикс проекта.

docker
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,rw

Сети в Compose

Compose создаёт сеть по умолчанию для всех сервисов, но явные сети позволяют изолировать уровни. web соединяет frontend и backend. internal: true блокирует доступ backend в интернет. Сервисы в одной сети находят друг друга по имени сервиса через DNS.

docker
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/16
13

Продвинутый Docker Compose

Профили Compose

Профили группируют необязательные сервисы. Сервисы без профиля запускаются всегда; сервисы с профилем — только когда профиль активирован через --profile. Так один compose-файл обслуживает dev, test и prod: включайте профили по окружениям.

docker
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 -d

Override-файлы Compose

Compose автоматически накладывает docker-compose.override.yml поверх docker-compose.yml для локальных настроек разработки. Для других окружений передавайте несколько файлов через -f по порядку — поздние переопределяют ранние. Это чисто разделяет базовую конфигурацию и правки под окружение.

docker
# 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 up

Healthcheck в Compose

healthcheck в Compose повторяет HEALTHCHECK из Dockerfile. start_period даёт запас времени при старте. Сочетание healthcheck с depends_on: condition: service_healthy заставляет сервис ждать реальной готовности зависимостей, а не просто их запуска.

docker
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_healthy

Масштабирование и реплики

--scale запускает N одинаковых контейнеров на одном хосте — сервис не должен занимать фиксированный порт хоста (используйте случайный порт или не пробрасывайте порт). Ключ deploy.replicas учитывается в Swarm; в обычном Compose используйте --scale. Перед масштабируемыми сервисами ставят балансировщик.

docker
# 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 ports

Config и валидация Compose

config валидирует и выводит итоговый объединённый compose-файл (включая override и подстановку из .env) — бесценно для отладки. --services, --images и --volumes показывают состав ресурсов. В CI используйте -q, чтобы быстро падать на битом compose-файле.

docker
# 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 -d

Несколько файлов Compose

Наложение compose-файлов разделяет ответственность: базовая конфигурация, override окружения, локальные правки. COMPOSE_FILE (разделённый двоеточиями на Linux/Mac, точкой с запятой на Windows) избавляет от повторения -f. Списки вроде ports дописываются; словари вроде environment объединяются по ключам.

docker
# 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 merged
14

Docker Registry

Запуск локального registry

Образ registry:2 поднимает приватный registry на порту 5000. Смонтируйте том, чтобы образы сохранялись. Для удалённых хостов или HTTPS настройте TLS-сертификаты или добавьте registry в insecure-registries в /etc/docker/daemon.json. API v2 позволяет перечислить репозитории через curl.

docker
# 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/list

Push в приватный registry

Перед push образы нужно пометить тегом с хостом registry. Для registry с самоподписанными сертификатами добавьте хост в insecure-registries и перезапустите демон (не рекомендуется для production — используйте настоящий или внутренний CA). push -a загружает все теги репозитория.

docker
# 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 docker

Pull из приватного registry

Чтобы загрузить образ из приватного registry, указывайте полное имя образа. Учётные данные для входа хранятся в ~/.docker/config.json (для безопасности используйте credential helper). В CI/CD храните учётные данные как секреты и логиньтесь перед pull. Фиксируйте digest для воспроизводимых деплоев.

docker
# 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.json

Аутентификация в registry

Защитите registry basic-аутентификацией htpasswd или token-сервером (OAuth). Для TLS смонтируйте сертификаты и слушайте 443. Credential helpers (credsStore) хранят пароли в связке ключей ОС, а не в открытом config.json — это необходимо для общих машин и CI.

docker
# 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 registry

HTTP API v2 позволяет управлять registry из скриптов. _catalog перечисляет репозитории; manifests описывают слои образа. Для удаления нужен REGISTRY_STORAGE_DELETE_ENABLED=true; удаляются манифесты, а blobs очищаются сборкой мусора (registry garbage-collect).

docker
# 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...

Сборка мусора

Удаление манифеста оставляет осиротевшие blobs до запуска сборки мусора. Остановите registry (или используйте --dry-run), чтобы не удалить используемые слои. В production запускайте GC регулярно, чтобы вернуть место от удалённых или заменённых образов. Путь config.yml — это конфигурация registry.

docker
# 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/registry
15

Docker Hub

Вход и выход

Предпочитайте access token вместо пароля — его можно отозвать и ограничить по правам. --password-stdin читает из stdin, не оставляя пароль в истории shell и списке процессов. Настройте credential helper, чтобы хранить учётные данные в связке ключей ОС, а не в открытом config.json.

docker
# 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 Token

Поиск образов

docker search ищет на Docker Hub из CLI с фильтрами по звёздам, официальному статусу и автоматическим сборкам. Официальные образы (library/nginx) проверены Docker — предпочитайте их как базу. Веб-интерфейс даёт более богатую фильтрацию по ОС, архитектуре и категории.

docker
# 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=nginx

Push на Docker Hub

Помечайте образы как username/repo:tag, затем push публикует их на Docker Hub. Репозиторий создаётся автоматически при первом push (по умолчанию публичный). push -a загружает все теги. Бесплатные аккаунты получают один приватный репозиторий; платные планы дают больше. Видимость репозитория задаётся в веб-интерфейсе Hub.

docker
# 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)

Автоматические сборки

Autobuilds Docker Hub связывают git-репозиторий и собирают образ при каждом push. Современные workflow предпочитают GitHub Actions с buildx и push: больше контроля, кеширование и мультиархитектурные сборки. Autobuilds Hub остаются простым вариантом для небольших проектов.

docker
# 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)

Организации и команды

Организации делят репозитории между командой с ролевым доступом. Команды получают права на уровне репозитория (read, write, admin). Сервисные аккаунты дают неличные токены для CI/CD — их можно отозвать и ротировать, не затрагивая людей. Используйте пространство имён orgname/repo.

docker
# 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.0

Доверие к образам (DCT)

Docker Content Trust (DCT) использует Notary для подписи тегов, гарантируя, что вы получаете именно тот образ, который опубликовал издатель. Включается через DOCKER_CONTENT_TRUST=1. При включённом DCT можно pull и push только подписанные образы. Аккуратно обращайтесь с ключами подписи — их потеря может закрыть доступ к вашим образам.

docker
# 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 CLI
16

Healthcheck

Базовый healthcheck

Healthcheck периодически выполняет команду; код выхода 0 — здоров, ненулевой — нездоров. Контейнер стартует в состоянии starting и становится healthy после успешных попыток или unhealthy после неудачных. start_period даёт запас времени при загрузке. Состояние здоровья влияет на решения Swarm о перезапуске.

docker
# 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 | none

Healthcheck в Dockerfile

HEALTHCHECK в Dockerfile «запекает» проверку в образ. Используйте самую лёгкую проверку, которая подтверждает, что приложение реально отвечает: curl -f или wget --spider для HTTP, pg_isready для Postgres. HEALTHCHECK NONE отключает унаследованную проверку. Слишком широкая проверка вызывает ложные переключения в unhealthy.

docker
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}}' myapp

Опции healthcheck

interval задаёт частоту проверок; timeout ограничивает каждую проверку; retries — порог последовательных неудач. start_period игнорирует ошибки при загрузке, предотвращая ложный unhealthy, пока приложение прогревается. Настройте их так, чтобы быстро ловить реальные сбои и не мигать под нагрузкой.

docker
# 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: 30s

Просмотр состояния здоровья

ps показывает (healthy)/(unhealthy) рядом со статусом. Health.Log хранит вывод последних 5 проверок — бесценно при выяснении, почему проверка падает. Запустите команду проверки вручную через exec, чтобы увидеть реальную ошибку. Фильтруйте ps по health, чтобы быстро находить больные контейнеры.

docker
# 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 в Compose

healthcheck в Compose повторяет Dockerfile. test принимает массив (exec-форма) или строку CMD-SHELL. disable: true убирает унаследованную проверку. Сочетайте healthcheck с depends_on: condition: service_healthy, чтобы сервис ждал реальной готовности зависимостей, а не просто их запуска.

docker
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: true

Лучшие практики healthcheck

Проверяйте реальный endpoint /healthz, который проверяет критичные зависимости (БД, кеш), — простая проверка TCP может проходить, когда приложение уже сломано. Держите проверки лёгкими и быстрыми: они выполняются каждый interval. Используйте start_period для медленно стартующих runtime (JVM, Rails), чтобы их не помечали unhealthy при загрузке.

docker
# 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'))
17

Ограничения ресурсов

Ограничения памяти

--memory задаёт жёсткий лимит; его превышение вызывает OOM kill. --memory-swap ограничивает суммарно память+swap; равенство memory отключает swap. --memory-reservation — мягкая подсказка ядру. Отключайте swap для предсказуемой производительности в latency-чувствительных нагрузках.

docker
# 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>

Ограничения CPU

--cpus задаёт лимит CPU в долях ядра (1.5 = 1.5 ядра). --cpu-shares — относительный вес при конкуренции, а не жёсткий предел. --cpuset-cpus привязывает контейнер к конкретным ядрам, что полезно для изоляции производительности. Quota/period — низкоуровневая форма cgroup.

docker
# 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 nginx

Поведение памяти и swap

memory-swap — это сумма памяти и swap. Равенство memory отключает swap. -1 разрешает неограниченный swap. Swappiness (0-100) управляет склонностью ядра к свопу; меньшие значения предпочитают держать страницы в RAM. Лимиты памяти ядра — продвинутая тема, нужны редко.

docker
# 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>

Ограничения ресурсов в Compose

deploy.resources.limits задаёт жёсткие пределы; reservations задают мягкие гарантии (используются планировщиком). Swarm поддерживает их нативно. Для обычного Compose (не Swarm) используйте mem_limit и cpus верхнего уровня в формате v2. Reservations позволяют контейнеру зарезервировать минимум даже в простое.

docker
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 и поведение перезапуска

Когда память исчерпана, OOM-killer ядра выбирает жертву. oom-kill-disable защищает контейнер, но может уронить хост — используйте только вместе с лимитами памяти хоста. oom-score-adj смещает выбор: положительное значение = убить первым, отрицательное = защитить. Проверяйте OOMKilled, чтобы понять причину перезапусков.

docker
# 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>

Просмотр использования ресурсов

docker stats в реальном времени показывает CPU, память, сеть и дисковый ввод-вывод по каждому контейнеру — основной инструмент быстрой диагностики. --no-stream даёт один снимок для скриптов. Для глубокого анализа читайте /sys/fs/cgroup или отдавайте метрики Prometheus через cAdvisor. Сравнивайте использование с лимитами, чтобы подобрать размеры.

docker
# 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}}' web
18

Безопасность

Пользователь не-root

Запуск не от root ограничивает ущерб при компрометации приложения. Создайте отдельного пользователя в Dockerfile и переключитесь на него через USER. Если нужен привилегированный порт, используйте reverse proxy (nginx) или выдайте capability NET_BIND_SERVICE вместо запуска от root.

docker
# 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 nonroot

Корневая файловая система только для чтения

Корневая файловая система только для чтения не даёт атакующему записать вредоносный код или изменить конфигурацию при компрометации. Дополните её tmpfs для временных каталогов (/tmp, /cache) и томами для постоянных данных. Приложение должно быть к этому готово — некоторые фреймворки пишут в неожиданные пути и требуют tmpfs.

docker
# 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 paths

Linux capabilities

По умолчанию Docker выдаёт ограниченный набор Linux capabilities. Сбросьте ALL и добавьте только то, что нужно приложению, — принцип наименьших привилегий. --privileged выдаёт все capabilities и доступ к устройствам хоста; избегайте его, кроме доверенных runtime контейнеров. По умолчанию отбросьте NET_RAW.

docker
# 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 и AppArmor

Seccomp фильтрует системные вызовы контейнера — профиль по умолчанию блокирует около 44 опасных вызовов. AppArmor ограничивает доступ к файлам и capabilities. no-new-privileges не даёт setuid-бинарникам получать новые привилегии — дешёвое и ценное укрепление для любого контейнера.

docker
# 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 nginx

Сканирование образов

Сканируйте образы на известные уязвимости (CVE) перед push. docker scout (ранее docker scan на базе snyk) встроен. Trivy и Grype — популярные альтернативы. Встройте сканирование в CI, чтобы блокировать образы с критичными CVE. Периодически пересканируйте базовые образы, так как появляются новые CVE.

docker
# 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 CVEs

Content Trust и укрепление

Content Trust гарантирует, что вы загружаете подписанные образы. Укрепите демон: отключите межконтейнерное взаимодействие (icc=false), включите live-restore, чтобы контейнеры переживали перезапуск демона, и включите user namespaces (userns-remap), чтобы сопоставить root контейнера с непривилегированным UID хоста для более сильной изоляции.

docker
# 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"
19

Логирование и мониторинг

Просмотр логов

docker logs читает stdout/stderr, захваченный logging driver. Приложения должны писать в stdout, а не в файлы, чтобы интегрироваться с docker logs. --tail и --since ограничивают вывод. logs в Compose собирает логи всех сервисов. Драйвер json-file по умолчанию растёт без ограничений, если не задать лимиты.

docker
# 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 db

Драйверы логирования

Драйвер json-file растёт без ротации — задайте max-size и max-file, чтобы не исчерпать диск. В production отправляйте логи в централизованную систему (fluentd, splunk, awslogs, gelf). Задайте глобальные значения по умолчанию в daemon.json, чтобы ротация была у всех контейнеров.

docker
# 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" } }

Теги и атрибуты логов

Шаблон tag настраивает идентификаторы логов: {{.Name}} даёт читаемые имена контейнеров вместо усечённых ID. Для fluentd/splunk метки и переменные окружения прикрепляются к записям логов для фильтрации. Задайте шаблоны тегов на уровне демона, чтобы все контейнеры тегировались одинаково.

docker
# 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 nginx

Статистика и мониторинг ресурсов

stats в реальном времени показывает CPU, память, сеть и блочный ввод-вывод. docker events — поток событий демона в реальном времени, полезен для скриптов оповещения. docker top показывает процессы внутри контейнера; docker diff — изменения файловой системы (A=добавлено, C=изменено, D=удалено) с момента создания образа.

docker
# 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 web

События Docker

docker events — поток событий жизненного цикла в реальном времени: create, start, stop, pause, die, destroy, а также события образов и сетей. Фильтруйте по типу, событию или контейнеру. Это основа скриптов оповещения, реагирующих на падение контейнеров или перезапускающих сбойные сервисы.

docker
# 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"
done

Стек Prometheus и Grafana

cAdvisor отдаёт метрики по каждому контейнеру (CPU, память, сеть, файловая система) в формате Prometheus. Prometheus собирает и хранит их; Grafana визуализирует. Это де-факто открытый стек мониторинга для Docker. Добавьте node-exporter для метрик хоста и alertmanager для оповещений.

docker
# 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:3000
20

Docker Swarm

Инициализация Swarm

swarm init превращает хост Docker в менеджер Swarm. Join-токен позволяет воркерам и дополнительным менеджерам присоединиться. Держите токены менеджеров в секрете — они дают контроль над кластером. Запускайте нечётное число менеджеров (3 или 5) для устойчивости консенсуса Raft. Воркеры выполняют задачи; менеджеры их планируют.

docker
# 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 leave

Развёртывание сервисов

Сервисы — это абстракция Swarm над контейнерами. Replicated-сервис запускает N одинаковых задач; global-сервис — по одной задаче на узел. update по умолчанию выкатывает новый образ без простоя. scale меняет число реплик на лету. Swarm сам перепланирует задачи при отказе узла.

docker
# 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 web

Масштабирование и обновления

scale мгновенно меняет число реплик. update выполняет rolling update: parallelism задаёт, сколько задач обновлять одновременно, delay разносит их по времени, а failure-action=rollback автоматически откатывает при ошибках. Swarm держит старые задачи до готовности новых — это даёт деплой без простоя.

docker
# 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 web

Деплой стека

Стек — это compose-файл, развёрнутый в Swarm. Ключ deploy: настраивает реплики, политики update/rollback, ограничения размещения и ресурсы — всё специфично для Swarm. docker stack deploy применяет спецификацию декларативно. Стеки группируют связанные сервисы, сети и секреты.

docker
# 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 mystack

Управление узлами

Перед обслуживанием переведите узел в drain, чтобы его задачи корректно переехали на другие. Состояния active/pause/drain управляют планированием. Метки задают ограничения размещения (например, запускать БД только на узлах с меткой tier=db). Удаляйте узел только после выхода из Swarm через docker swarm leave.

docker
# 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)

Секреты и конфиги

Секреты шифруются при хранении и передаче, монтируются как файлы в /run/secrets и никогда не попадают в слои образа или переменные окружения. Они неизменяемы: для ротации создайте новый секрет и обновите сервис. Configs устроены так же, но для несекретных данных вроде файлов конфигурации. И то и другое работает только в Swarm.

docker
# 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 ls

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.