Category Reference

Docker

컨테이너 개념, 이미지 빌드, buildx, 실행 흐름, 네트워크, Compose, secret과 운영 정책까지 Docker의 핵심 흐름을 카드형 레퍼런스로 정리합니다.

Search cards

40 cards

Search titles, summaries, tags, and subcategories.

소개와 개념

3 cards

소개와 개념

컨테이너와 Docker 개요

컨테이너가 무엇이고 Docker가 무엇을 자동화하는지, 개발 환경 일관성과 배포 재현성 관점에서 정리하는 입문 카드입니다.

# 이미지를 내려받아 컨테이너로 실행
docker run -d -p 8080:80 nginx:alpine

# 실행 중인 컨테이너 확인
docker ps

# 로그 확인
docker logs <container-id>

소개와 개념

이미지와 컨테이너 차이

Docker 입문에서 가장 자주 헷갈리는 이미지와 컨테이너의 차이를 정적 청사진과 실행 인스턴스 관점에서 정리합니다.

# 이미지 하나로 컨테이너 여러 개 실행
docker pull nginx:alpine
docker run -d --name web1 nginx:alpine
docker run -d --name web2 nginx:alpine
docker run -d --name web3 nginx:alpine

소개와 개념

client, daemon, objects

Docker CLI가 데몬과 통신해 이미지, 컨테이너, 네트워크, 볼륨 같은 객체를 관리하는 구조를 정리합니다.

# CLI(클라이언트)가 데몬으로 명령을 전달하는 흐름
docker info          # 데몬 상태 확인
docker ps            # 컨테이너 객체 목록
docker images        # 이미지 객체 목록
docker network ls    # 네트워크 객체 목록
docker volume ls     # 볼륨 객체 목록

기본 흐름

3 cards

기본 흐름

docker run 기본

이미지를 처음 실행할 때 가장 자주 쓰는 docker run 옵션을 중심으로 이름, 포트, 환경 변수, 삭제 흐름을 정리합니다.

docker run \
  --name web \
  -d \
  -p 8080:80 \
  -e NGINX_HOST=example.com \
  --rm \
  nginx:alpine

기본 흐름

컨테이너 생명주기와 기본 명령

컨테이너를 생성한 뒤 상태를 확인하고 시작, 중지, 삭제하는 기본 생명주기 명령을 정리합니다.

docker run --name web -d nginx:alpine   # created → running
docker ps                               # 실행 중 확인
docker stop web                         # running → stopped
docker start web                        # stopped → running
docker rm web                           # 컨테이너 삭제

기본 흐름

env file과 변수 전달

컨테이너 실행 시 환경 변수를 넘기는 기본 방법과 `--env-file`의 역할을 정리합니다.

# .env 파일 예시
# DB_HOST=db
# DB_PORT=5432
# APP_ENV=production

docker run --env-file .env -e PORT=4000 my-app

이미지와 빌드

13 cards

이미지와 빌드

Dockerfile 기본

FROM, WORKDIR, COPY, RUN, CMD 같은 핵심 지시어를 기준으로 Dockerfile이 이미지를 만드는 방식을 정리합니다.

FROM node:22-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["npm", "start"]

이미지와 빌드

build context와 cache

Docker 빌드 속도와 이미지 효율을 좌우하는 build context와 레이어 캐시의 동작 원리를 정리합니다.

FROM node:22-alpine
WORKDIR /app

# 의존성 파일만 먼저 복사 — 소스 변경이 캐시에 영향 없음
COPY package.json package-lock.json ./
RUN npm ci

# 소스 코드는 나중에 — 자주 바뀌는 파일을 뒤에 둔다
COPY . .
RUN npm run build

이미지와 빌드

image tag와 push

이미지 이름과 태그가 버전 식별과 배포 경로를 결정한다는 점을 중심으로 build, tag, push 흐름을 정리합니다.

docker build -t myname/my-app:1.2.3 .
docker push myname/my-app:1.2.3

이미지와 빌드

multi-stage build 기본

빌드 도구와 런타임 이미지를 분리하는 multi-stage build의 핵심 목적과 패턴을 정리합니다.

FROM node:22-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html

이미지와 빌드

ENTRYPOINT와 CMD 차이

컨테이너 시작 명령을 구성할 때 `ENTRYPOINT`와 `CMD`가 각각 어떤 역할을 맡는지 정리합니다.

FROM python:3.12-slim
WORKDIR /app
COPY . .

ENTRYPOINT ["python", "-m", "http.server"]
CMD ["8000"]

이미지와 빌드

ARG와 ENV 차이

빌드 시점 변수 ARG와 런타임 환경 변수 ENV를 어떻게 구분해야 하는지 정리합니다.

ARG NODE_VERSION=22
FROM node:${NODE_VERSION}-alpine

ENV NODE_ENV=production
ENV PORT=3000

이미지와 빌드

.dockerignore와 build context 관리

이미지 빌드가 느리고 예상보다 무거워질 때 자주 원인이 되는 build context와 .dockerignore의 역할을 정리합니다.

# .dockerignore
node_modules
.git
dist
.env
*.log
coverage
.DS_Store

이미지와 빌드

buildx와 multi-platform image

한 아키텍처만이 아니라 amd64와 arm64 같은 여러 플랫폼용 이미지를 함께 빌드하고 배포할 때 쓰는 buildx의 기본 흐름을 정리합니다.

# buildx 빌더 생성 (처음 한 번)
docker buildx create --name mybuilder --use

# amd64와 arm64를 동시에 빌드해 레지스트리에 푸시
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myorg/myapp:1.0.0 \
  --push .

이미지와 빌드

Dockerfile USER와 non-root 실행

컨테이너 기본 실행 사용자를 root에서 별도 사용자로 바꾸는 `USER` 지시어의 위치와 파일 권한 설계 기준을 정리합니다.

FROM node:22-alpine
WORKDIR /app

RUN addgroup -S app && adduser -S app -G app
COPY --chown=app:app package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --chown=app:app . .

USER app
CMD ["node", "server.js"]

이미지와 빌드

image digest와 tag pinning

Docker 이미지 태그가 움직일 수 있다는 점과 digest로 특정 이미지 버전을 고정할 때의 장단점을 정리합니다.

docker pull ubuntu:24.04

이미지와 빌드

Dockerfile COPY와 ADD

Dockerfile에서 COPY와 ADD를 구분하고, 로컬 파일 복사, tar 자동 해제, 원격 URL·Git source 사용 시 경계를 정리합니다.

# 일반 파일과 디렉터리 복사
COPY package.json package-lock.json ./
COPY src/ ./src/

# 멀티 스테이지 산출물 복사
COPY --from=build /app/dist ./dist

# tar 자동 해제나 원격 source가 필요한 경우에만 ADD 검토
ADD archive.tar.gz /opt/archive/
ADD --checksum=sha256:<hash> https://example.com/file.tar.gz /tmp/

이미지와 빌드

docker login과 credential store

docker login/logout, Docker Hub device flow, self-hosted registry 주소, --password-stdin, credential store와 helper 설정 기준입니다.

# Docker Hub device flow
docker login

# 사용자명 지정
docker login -u <username>

# self-hosted registry
docker login registry.example.com
docker login registry.example.com:5000

# CI나 스크립트
cat token.txt | docker login --username <user> --password-stdin

# 인증 제거
docker logout registry.example.com

이미지와 빌드

docker save/load와 image archive

레지스트리 없이 Docker 이미지를 tar archive로 옮길 때 docker save/load와 export/import의 차이, 태그 보존, 검증 흐름을 정리합니다.

# 이미지와 태그를 tar archive로 저장
docker image save -o my-app.tar myorg/my-app:1.2.3

# gzip 압축과 함께 저장
docker image save myorg/my-app:1.2.3 | gzip > my-app.tar.gz

# 다른 머신에서 이미지 복원
docker image load -i my-app.tar
gunzip -c my-app.tar.gz | docker image load

# 복원 확인
docker image ls myorg/my-app
docker run --rm myorg/my-app:1.2.3 --version

데이터와 네트워크

4 cards

데이터와 네트워크

bind mount와 volume 차이

개발 편의성과 데이터 영속성 요구에 따라 bind mount와 volume 중 무엇을 고를지 판단하는 카드입니다.

# bind mount — 호스트 경로를 그대로 마운트
docker run -v "$(pwd)/src":/app/src node:22-alpine

# named volume — Docker가 관리하는 전용 저장소
docker run -v pgdata:/var/lib/postgresql/data postgres:16

# tmpfs — 메모리 기반 임시 저장소
docker run --tmpfs /tmp:rw,size=64m my-app

데이터와 네트워크

포트 공개와 bridge 네트워크

호스트와 컨테이너 사이의 포트 연결, 그리고 컨테이너끼리의 통신에서 bridge 네트워크가 어떤 역할을 하는지 정리합니다.

docker run --name web -d -p 8080:80 nginx:alpine

데이터와 네트워크

named network와 service discovery

컨테이너끼리 이름으로 통신하려면 named network와 Docker의 서비스 발견 방식을 함께 이해해야 합니다.

docker network create appnet
docker run -d --name db --network appnet postgres:17
docker run -d --name api --network appnet my-api
# api 컨테이너 안에서 db라는 이름으로 postgres에 접근 가능

데이터와 네트워크

volume backup과 restore

Docker named volume 데이터를 tar로 백업하고 새 volume으로 복구할 때의 안전한 순서와 검증 기준을 정리합니다.

docker compose stop db
docker run --rm -v app_pgdata:/data -v "$PWD":/backup alpine tar czf /backup/pgdata.tgz -C /data .
docker volume create app_pgdata_restore
docker run --rm -v app_pgdata_restore:/data -v "$PWD":/backup alpine tar xzf /backup/pgdata.tgz -C /data
docker run --rm -v app_pgdata_restore:/data alpine ls -la /data

Compose와 멀티컨테이너

6 cards

Compose와 멀티컨테이너

Compose 기본

여러 docker run 명령을 흩어 놓는 대신 compose.yaml 하나로 앱, DB, 볼륨, 네트워크를 선언하는 기본 흐름을 정리합니다.

services:
  app:
    build: .
    ports:
      - "3000:3000"
    depends_on:
      - db
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Compose와 멀티컨테이너

depends_on과 healthcheck

Compose에서 서비스 시작 순서를 제어하되, 실행 순서와 준비 완료 상태는 다르다는 점을 healthcheck와 함께 정리합니다.

services:
  web:
    build: .
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

Compose와 멀티컨테이너

Compose override 파일

환경별 차이를 Compose 파일 분리로 관리하는 기본 패턴을 정리합니다.

# -f로 파일을 명시하면 뒤에 오는 파일이 앞 설정을 덮어씀
docker compose -f compose.yaml -f compose.dev.yaml up -d

# 운영 환경
docker compose -f compose.yaml -f compose.prod.yaml up -d

Compose와 멀티컨테이너

Compose profiles 기본

선택적 서비스 기동을 위한 Compose profiles 기능의 기본 목적과 사용 흐름을 정리합니다.

services:
  app:
    build: .           # profile 없음 → 항상 실행

  adminer:
    image: adminer
    profiles:
      - debug          # --profile debug 할 때만 실행

  prometheus:
    image: prom/prometheus
    profiles:
      - monitoring     # --profile monitoring 할 때만 실행

Compose와 멀티컨테이너

Compose project name과 이름 충돌

Compose가 project name으로 컨테이너, 네트워크, 볼륨 이름을 격리하는 방식과 CI·브랜치별 충돌을 피하는 기준을 정리합니다.

docker compose -p myapp-dev up -d

COMPOSE_PROJECT_NAME=myapp-ci-123 docker compose up -d

docker compose ls
docker compose -p myapp-dev down

Compose와 멀티컨테이너

Compose variable interpolation

Docker Compose의 ${VAR} 치환, .env 파일, --env-file, environment/env_file과 컨테이너 환경 변수의 차이를 구분합니다.

services:
  web:
    image: "webapp:${TAG:-latest}"
    ports:
      - "${WEB_PORT:-8080}:80"
    environment:
      - DEBUG=${DEBUG:-false}

운영과 디버깅

11 cards

운영과 디버깅

inspect, exec, debug 기본

실행 중인 컨테이너 내부를 확인하고, 셸에 들어가고, 설정과 포트 매핑을 읽는 기본 디버깅 흐름을 정리합니다.

docker logs --follow app
docker exec -it app sh
docker inspect app

운영과 디버깅

prune과 cleanup

실험 후 남은 중지 컨테이너, dangling 이미지, 미사용 네트워크와 볼륨을 안전하게 정리하는 기본 카드를 정리합니다.

# 디스크 사용량 확인 후 정리
docker system df
docker system prune

운영과 디버깅

CPU와 메모리 제한 기본

컨테이너가 호스트 자원을 무제한 쓰지 않도록 docker run 단계에서 메모리와 CPU 제한을 거는 기본 패턴을 정리합니다.

docker run --memory=512m --cpus=1.5 my-app:latest

운영과 디버깅

restart policy 기본

컨테이너 재시작 정책을 통해 장애 후 동작을 어느 수준까지 자동화할 수 있는지 정리합니다.

docker run -d --restart unless-stopped my-app

운영과 디버깅

healthcheck와 container readiness

컨테이너가 단순히 떠 있는 상태와 실제로 요청을 받을 준비가 된 상태가 왜 다른지, healthcheck를 어떤 기준으로 설계하는지 정리합니다.

HEALTHCHECK --interval=30s --timeout=3s --retries=3 --start-period=10s \
  CMD curl -f http://localhost:3000/health || exit 1

운영과 디버깅

secret과 민감한 설정 관리

비밀번호와 API 키 같은 민감한 값을 이미지에 굳히지 않고 안전하게 전달하는 기본 원칙을 정리합니다.

# docker-compose.yml
services:
  app:
    image: my-app
    secrets:
      - db_password
    environment:
      DB_PASSWORD_FILE: /run/secrets/db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt

운영과 디버깅

context와 remote daemon

Docker CLI가 어떤 daemon을 대상으로 명령을 실행하는지 context로 전환하고, remote daemon을 다룰 때 필요한 보안 경계를 정리합니다.

docker context ls
docker context inspect default
docker context create staging --docker "host=ssh://deploy@staging.example.com"
docker context use staging
docker --context default ps

운영과 디버깅

docker events와 lifecycle 추적

컨테이너가 언제 생성, 시작, 종료, 제거되었는지 Docker daemon 이벤트 스트림으로 확인하는 방법을 정리합니다.

docker events
docker events --since 10m
docker events --filter "type=container"
docker events --filter "container=app" --filter "event=die"
docker events --format "{{.Time}} {{.Type}} {{.Action}} {{json .Actor.Attributes}}"

운영과 디버깅

docker cp와 container filesystem

컨테이너와 호스트 사이에서 파일을 복사할 때 경로 해석, 권한, 중지 컨테이너 처리 기준을 정리합니다.

docker cp ./config.json app:/etc/app/config.json
docker cp app:/var/log/app.log ./app.log
docker cp app:/var/log ./logs
docker cp app:/var/log/app.log - | tar x -O
docker cp -a app:/data ./data-copy

운영과 디버깅

docker stats와 resource 관찰

컨테이너의 CPU, 메모리, 네트워크, 디스크 I/O, PID 사용량을 docker stats로 확인하고 한계값 판단에 연결하는 방법을 정리합니다.

docker stats
docker stats app worker
docker stats --no-stream
docker stats --all
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.PIDs}}"

운영과 디버깅

docker logs와 log driver

docker logs가 stdout/stderr를 어떻게 보여 주는지와 json-file, local, 원격 logging driver 선택 시 확인할 지점을 정리합니다.

docker logs app
docker logs -f --tail 100 app
docker logs --since 10m app

docker info --format '{{.LoggingDriver}}'
docker inspect -f '{{.HostConfig.LogConfig.Type}}' app

Loading category cards

Preparing references and filters for this topic. 이 주제의 레퍼런스와 필터를 준비하고 있습니다.

# CLI(클라이언트)가 데몬으로 명령을 전달하는 흐름 docker info # 데몬 상태 확인 docker ps # 컨테이너 객체 목록 docker images # 이미지 객체 목록 docker network ls # 네트워크 객체 목록 docker volume ls # 볼륨 객체 목록

docker run --name web -d nginx:alpine # created → running docker ps # 실행 중 확인 docker stop web # running → stopped docker start web # stopped → running docker rm web # 컨테이너 삭제

FROM node:22-alpine WORKDIR /app # 의존성 파일만 먼저 복사 — 소스 변경이 캐시에 영향 없음 COPY package.json package-lock.json ./ RUN npm ci # 소스 코드는 나중에 — 자주 바뀌는 파일을 뒤에 둔다 COPY . . RUN npm run build

# buildx 빌더 생성 (처음 한 번) docker buildx create --name mybuilder --use # amd64와 arm64를 동시에 빌드해 레지스트리에 푸시 docker buildx build \ --platform linux/amd64,linux/arm64 \ -t myorg/myapp:1.0.0 \ --push .

FROM node:22-alpine WORKDIR /app RUN addgroup -S app && adduser -S app -G app COPY --chown=app:app package.json package-lock.json ./ RUN npm ci --omit=dev COPY --chown=app:app . . USER app CMD ["node", "server.js"]

# 일반 파일과 디렉터리 복사 COPY package.json package-lock.json ./ COPY src/ ./src/ # 멀티 스테이지 산출물 복사 COPY --from=build /app/dist ./dist # tar 자동 해제나 원격 source가 필요한 경우에만 ADD 검토 ADD archive.tar.gz /opt/archive/ ADD --checksum=sha256:<hash> https://example.com/file.tar.gz /tmp/

# Docker Hub device flow docker login # 사용자명 지정 docker login -u <username> # self-hosted registry docker login registry.example.com docker login registry.example.com:5000 # CI나 스크립트 cat token.txt | docker login --username <user> --password-stdin # 인증 제거 docker logout registry.example.com

# 이미지와 태그를 tar archive로 저장 docker image save -o my-app.tar myorg/my-app:1.2.3 # gzip 압축과 함께 저장 docker image save myorg/my-app:1.2.3 | gzip > my-app.tar.gz # 다른 머신에서 이미지 복원 docker image load -i my-app.tar gunzip -c my-app.tar.gz | docker image load # 복원 확인 docker image ls myorg/my-app docker run --rm myorg/my-app:1.2.3 --version

# bind mount — 호스트 경로를 그대로 마운트 docker run -v "$(pwd)/src":/app/src node:22-alpine # named volume — Docker가 관리하는 전용 저장소 docker run -v pgdata:/var/lib/postgresql/data postgres:16 # tmpfs — 메모리 기반 임시 저장소 docker run --tmpfs /tmp:rw,size=64m my-app

docker network create appnet docker run -d --name db --network appnet postgres:17 docker run -d --name api --network appnet my-api # api 컨테이너 안에서 db라는 이름으로 postgres에 접근 가능

docker compose stop db docker run --rm -v app_pgdata:/data -v "$PWD":/backup alpine tar czf /backup/pgdata.tgz -C /data . docker volume create app_pgdata_restore docker run --rm -v app_pgdata_restore:/data -v "$PWD":/backup alpine tar xzf /backup/pgdata.tgz -C /data docker run --rm -v app_pgdata_restore:/data alpine ls -la /data

services: app: build: . ports: - "3000:3000" depends_on: - db db: image: postgres:16 environment: POSTGRES_PASSWORD: secret volumes: - pgdata:/var/lib/postgresql/data volumes: pgdata:

services: web: build: . depends_on: db: condition: service_healthy db: image: postgres:16 healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 10s timeout: 5s retries: 5

# -f로 파일을 명시하면 뒤에 오는 파일이 앞 설정을 덮어씀 docker compose -f compose.yaml -f compose.dev.yaml up -d # 운영 환경 docker compose -f compose.yaml -f compose.prod.yaml up -d

services: app: build: . # profile 없음 → 항상 실행 adminer: image: adminer profiles: - debug # --profile debug 할 때만 실행 prometheus: image: prom/prometheus profiles: - monitoring # --profile monitoring 할 때만 실행

# docker-compose.yml services: app: image: my-app secrets: - db_password environment: DB_PASSWORD_FILE: /run/secrets/db_password secrets: db_password: file: ./secrets/db_password.txt

docker events docker events --since 10m docker events --filter "type=container" docker events --filter "container=app" --filter "event=die" docker events --format "{{.Time}} {{.Type}} {{.Action}} {{json .Actor.Attributes}}"