9.2. Справочник по services

services:
  a:
    image: postgres:17-alpine          # только скачать

  b:
    build: .                           # только собрать

  c:
    build:
      context: .
      dockerfile: Dockerfile.dev
      target: dev
      args:
        UID: "${UID:-1000}"
      cache_from:
        - myapp:cache
    image: myapp:local                 # собрать И назвать этим именем

services:
  app:
    image: myapp
    entrypoint: ["/entrypoint.sh"]
    command: ["--port", "8000"]

services:
  app:
    env_file:
      - .env.common
      - .env.local
    environment:
      LOG_LEVEL: debug
      DATABASE_URL: "postgresql://user:pass@db:5432/app"
      EMPTY_ON_PURPOSE: ""
      FROM_SHELL:                     # без значения — взять из окружения shell

services:
  web:
    ports:
      - "8080:80"                     # host:container
      - "127.0.0.1:8081:80"           # только с host
      - "8082:80/udp"
      - "3000-3005:3000-3005"
      - target: 80                    # длинная форма
        published: "8083"
        protocol: tcp
        mode: host
    expose:
      - "9000"                        # только объявление

services:
  app:
    volumes:
      - app-data:/data                          # named volume
      - ./src:/app/src                          # bind mount, путь от файла
      - ./config:/etc/app:ro                    # только чтение
      - /tmp/cache                              # anonymous volume
      - type: bind                              # длинная форма
        source: ./logs
        target: /var/log/app
        read_only: false

services:
  app:
    # Форма 1: работает и без Swarm
    deploy:
      resources:
        limits:
          cpus: "1.5"
          memory: 512M
          pids: 200
        reservations:
          cpus: "0.25"
          memory: 128M

    # Форма 2: краткие ключи Compose
    mem_limit: 512m
    cpus: 1.5
    pids_limit: 200

services:
  app:
    restart: unless-stopped

services:
  worker:
    stop_grace_period: 30s
    stop_signal: SIGINT
    init: true

services:
  db:
    container_name: my-database        # не делайте так

mkdir -p /tmp/svcref && cd /tmp/svcref

cat > Dockerfile <<'EOF'
FROM python:3.13-slim
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
ENTRYPOINT ["/entrypoint.sh"]
CMD ["аргумент-из-образа"]
EOF

cat > entrypoint.sh <<'EOF'
#!/bin/sh
echo "точка входа получила: [$*]"
EOF

cat > compose.yaml <<'EOF'
name: svcref

services:
  as-is:
    build: .

  only-command:
    build: .
    command: ["свой-аргумент"]

  only-entrypoint:
    build: .
    entrypoint: ["/entrypoint.sh"]

  both:
    build: .
    entrypoint: ["/entrypoint.sh"]
    command: ["и-точка-входа", "и-аргументы"]
EOF

docker compose build -q > /dev/null 2>&1
for s in as-is only-command only-entrypoint both; do
    printf '  %-16s ' "$s"
    docker compose run --rm -T "$s" 2>/dev/null
done

  as-is            точка входа получила: [аргумент-из-образа]
  only-command     точка входа получила: [свой-аргумент]
  only-entrypoint  точка входа получила: []
  both             точка входа получила: [и-точка-входа и-аргументы]

cd /tmp/svcref
cat > .env.common <<'EOF'
LEVEL=из-env-file-1
COMMON_ONLY=только-в-common
EOF

cat > .env.local <<'EOF'
LEVEL=из-env-file-2
LOCAL_ONLY=только-в-local
EOF

cat > compose.yaml <<'EOF'
name: svcref

services:
  show:
    image: python:3.13-slim
    env_file:
      - .env.common
      - .env.local
    environment:
      LEVEL: из-environment
      FROM_SHELL:
    command:
      - python
      - -c
      - |
        import os
        for k in ("LEVEL", "COMMON_ONLY", "LOCAL_ONLY", "FROM_SHELL"):
            print(f"  {k:<12} = {os.environ.get(k, '(отсутствует)')}")
EOF

echo "═══ без FROM_SHELL в окружении ═══"
docker compose run --rm -T show 2>/dev/null

echo "═══ с FROM_SHELL в окружении ═══"
FROM_SHELL=значение-из-shell docker compose run --rm -T show 2>/dev/null

echo "═══ переопределение через run -e ═══"
docker compose run --rm -T -e LEVEL=из-флага show 2>/dev/null | head -1

═══ без FROM_SHELL в окружении ═══
  LEVEL        = из-environment
  COMMON_ONLY  = только-в-common
  LOCAL_ONLY   = только-в-local
  FROM_SHELL   = (отсутствует)
═══ с FROM_SHELL в окружении ═══
  LEVEL        = из-environment
  COMMON_ONLY  = только-в-common
  LOCAL_ONLY   = только-в-local
  FROM_SHELL   = значение-из-shell
═══ переопределение через run -e ═══
  LEVEL        = из-флага

cd /tmp/svcref
cat > compose.yaml <<'EOF'
name: svcref

services:
  quoted:
    image: alpine:3.21
    command: ["true"]
    ports:
      - "22:22"
      - "8080:80"
    user: "1000:1000"

  unquoted:
    image: alpine:3.21
    command: ["true"]
    ports:
      - 22:22
      - 8080:80
EOF

echo "═══ как разобрал парсер ═══"
docker compose config 2>/dev/null | python3 -c "
import sys, yaml
cfg = yaml.safe_load(sys.stdin)
for name, svc in cfg['services'].items():
    print(f'  {name}:')
    for p in svc.get('ports', []):
        pub = p.get('published') if isinstance(p, dict) else p
        tgt = p.get('target') if isinstance(p, dict) else ''
        print(f'    published={pub!r} target={tgt!r}')
    if 'user' in svc:
        print(f'    user={svc[\"user\"]!r}')
"

═══ как разобрал парсер ═══
  quoted:
    published='22' target=22
    published='8080' target=80
    user='1000:1000'
  unquoted:
    published='22' target=22
    published='8080' target=80

cd /tmp/svcref
cat > compose.yaml <<'EOF'
name: svcref

services:
  limited:
    image: python:3.13-slim
    command: ["sleep", "300"]
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 256M
          pids: 100

  short-form:
    image: python:3.13-slim
    command: ["sleep", "300"]
    mem_limit: 128m
    cpus: 0.25
    pids_limit: 50
EOF

docker compose up -d > /dev/null 2>&1
sleep 3

for s in limited short-form; do
    cid="$(docker compose ps -q "$s")"
    printf '  %s:\n' "$s"
    printf '    memory.max: %s MiB\n' \
        "$(docker exec "$cid" awk '{printf "%.0f", $1/1048576}' /sys/fs/cgroup/memory.max)"
    printf '    cpu.max:    %s\n' "$(docker exec "$cid" cat /sys/fs/cgroup/cpu.max)"
    printf '    pids.max:   %s\n' "$(docker exec "$cid" cat /sys/fs/cgroup/pids.max)"
done
docker compose down > /dev/null 2>&1

  limited:
    memory.max: 256 MiB
    cpu.max:    50000 100000
    pids.max:   100
  short-form:
    memory.max: 128 MiB
    cpu.max:    25000 100000
    pids.max:   50

cd /tmp/svcref
cat > compose.yaml <<'EOF'
name: svcref

services:
  app:
    image: alpine:3.21
    command: ["sleep", "60"]
    deploy:
      replicas: 2
      restart_policy:
        condition: on-failure
      placement:
        constraints:
          - node.role == manager
EOF

docker compose up -d 2>&1 | grep -iE 'warn|ignor' | sed 's/^/  /' || true
printf '  запущено container: %s\n' "$(docker compose ps -q | wc -l)"
docker compose ps --format '    {{.Name}}'
docker compose down > /dev/null 2>&1

  запущено container: 2
    svcref-app-1
    svcref-app-2

cd /tmp/svcref
cat > compose.yaml <<'EOF'
name: svcref

services:
  named:
    image: alpine:3.21
    container_name: fixed-name
    command: ["sleep", "60"]
EOF

echo "═══ одна реплика ═══"
docker compose up -d > /dev/null 2>&1
docker compose ps --format '  {{.Name}}'

echo "═══ попытка масштабировать ═══"
docker compose up -d --scale named=3 2>&1 | tail -2 | sed 's/^/  /'
docker compose down > /dev/null 2>&1

echo "═══ без container_name ═══"
cat > compose.yaml <<'EOF'
name: svcref

services:
  named:
    image: alpine:3.21
    command: ["sleep", "60"]
EOF
docker compose up -d --scale named=3 > /dev/null 2>&1
docker compose ps --format '  {{.Name}}'
docker compose down > /dev/null 2>&1

═══ одна реплика ═══
  fixed-name
═══ попытка масштабировать ═══
  Error response from daemon: Conflict. The container name "/fixed-name" is
  already in use. You have to remove (or rename) that container to be able to
  reuse that name.
═══ без container_name ═══
  svcref-named-1
  svcref-named-2
  svcref-named-3

cd /tmp/svcref
cat > worker.py <<'PY'
"""Worker с долгой задачей: показывает работу stop_grace_period."""
import signal
import sys
import time

_stop = False


def handler(signum, _frame):
    global _stop
    print(f"получен {signal.Signals(signum).name}", flush=True)
    _stop = True


signal.signal(signal.SIGTERM, handler)
signal.signal(signal.SIGINT, handler)

print("работаю", flush=True)
while not _stop:
    time.sleep(0.2)

print("доделываю задачу (5 секунд)", flush=True)
time.sleep(5)
print("завершён штатно", flush=True)
sys.exit(0)
PY

cat > compose.yaml <<'EOF'
name: svcref

services:
  short-grace:
    image: python:3.13-slim
    volumes:
      - ./worker.py:/worker.py:ro
    command: ["python", "-u", "/worker.py"]
    stop_grace_period: 2s

  long-grace:
    image: python:3.13-slim
    volumes:
      - ./worker.py:/worker.py:ro
    command: ["python", "-u", "/worker.py"]
    stop_grace_period: 30s

  sigint:
    image: python:3.13-slim
    volumes:
      - ./worker.py:/worker.py:ro
    command: ["python", "-u", "/worker.py"]
    stop_signal: SIGINT
    stop_grace_period: 30s
EOF

docker compose up -d > /dev/null 2>&1
sleep 3

for s in short-grace long-grace sigint; do
    cid="$(docker compose ps -q "$s")"
    start="$(date +%s.%N)"
    docker compose stop "$s" > /dev/null 2>&1
    end="$(date +%s.%N)"
    printf '  %-12s время=%.1f c  код=%s  сигнал=%s\n' \
        "$s" \
        "$(awk -v a="$start" -v b="$end" 'BEGIN{print b-a}')" \
        "$(docker inspect "$cid" --format '{{.State.ExitCode}}')" \
        "$(docker logs "$cid" 2>&1 | grep -o 'SIG[A-Z]*' | head -1)"
done
docker compose down > /dev/null 2>&1

  short-grace  время=2.2 c  код=137  сигнал=SIGTERM
  long-grace   время=5.3 c  код=0    сигнал=SIGTERM
  sigint       время=5.3 c  код=0    сигнал=SIGINT

cd /tmp/svcref
cat > spawner.py <<'PY'
"""Порождает потомков и не пожинает их — классический источник зомби."""
import os
import time

for _ in range(5):
    if os.fork() == 0:
        time.sleep(0.5)
        os._exit(0)

time.sleep(3)
zombies = 0
for pid in os.listdir("/proc"):
    if not pid.isdigit():
        continue
    try:
        with open(f"/proc/{pid}/stat") as f:
            if f.read().split()[2] == "Z":
                zombies += 1
    except OSError:
        pass
print(f"зомби-процессов: {zombies}", flush=True)
print(f"PID 1: {open('/proc/1/comm').read().strip()}", flush=True)
PY

cat > compose.yaml <<'EOF'
name: svcref

services:
  no-init:
    image: python:3.13-slim
    volumes:
      - ./spawner.py:/spawner.py:ro
    command: ["python", "-u", "/spawner.py"]

  with-init:
    image: python:3.13-slim
    init: true
    volumes:
      - ./spawner.py:/spawner.py:ro
    command: ["python", "-u", "/spawner.py"]
EOF

for s in no-init with-init; do
    printf '  %s:\n' "$s"
    docker compose run --rm -T "$s" 2>/dev/null | sed 's/^/    /'
done
docker compose down > /dev/null 2>&1
cd /tmp && rm -rf /tmp/svcref

  no-init:
    зомби-процессов: 5
    PID 1: python
  with-init:
    зомби-процессов: 0
    PID 1: docker-init

mkdir -p /tmp/sr && cd /tmp/sr
cat > compose.yaml <<'EOF'
name: sr
services:
  a:
    image: alpine:3.21
    command: ["sleep", "60"]
    user: "1000:1000"
    read_only: true
    tmpfs:
      - /tmp:size=8m
    deploy:
      resources:
        limits:
          memory: 64M
EOF
docker compose up -d
docker compose exec -T a sh -c 'id -u; cat /sys/fs/cgroup/memory.max; touch /probe 2>&1 | tail -1'
docker compose down
cd /tmp && rm -rf /tmp/sr