확대

세 가지 핵심 개념

Docker를 처음 배울 때 가장 헷갈리는 것이 이미지와 컨테이너의 차이입니다. 친숙한 비유로 설명합니다.

소스코드 → 실행 파일 → 실행 중인 프로그램에 빗대면:

하나의 이미지로 여러 컨테이너를 동시에 실행할 수 있습니다. nginx 이미지 하나로 포트 8080, 8081, 8082에 컨테이너 3개를 띄울 수 있습니다.

이미지 하나가 여러 컨테이너로 실행되는 흐름입니다.

1. 레지스트리 (Docker Hub / ECR / GCR) → docker pull
2. 이미지 (로컬 캐시) — nginx:latest, ubuntu:22.04, myapp:v1.2.3 → docker run (여러 개 가능)
3. 컨테이너 — 같은 이미지로 여러 개:
   • 컨테이너 A (web-prod) — 포트 8080
   • 컨테이너 B (web-staging) — 포트 8081
   • 컨테이너 C (web-test) — 포트 8082

docker run 실행 시 일어나는 일

# 실습 디렉토리 준비
mkdir -p /tmp/docker/part1/exam_2 && cd /tmp/docker/part1/exam_2

docker run -d -p 8080:80 --name my-nginx nginx:latest

이 명령을 실행하면 Docker가 순서대로 다음을 수행합니다:

1. 로컬 이미지 캐시에서 nginx:latest 검색
2. 없으면 Docker Hub에서 자동으로 pull
3. 이미지를 기반으로 새 컨테이너 생성 (쓰기 가능한 레이어 추가)
4. 네트워크 설정 (가상 NIC 생성, IP 할당)
5. 포트 바인딩 (호스트 8080 → 컨테이너 80)
6. 컨테이너 내부에서 nginx 프로세스 실행

docker run -d -p 8080:80 --name web nginx 한 줄. Enter를 누르면 몇 초 뒤 docker ps에 web 컨테이너가 Up으로 뜹니다. 그 짧은 사이 Docker는 이미지 확인 → 쓰기 레이어 생성 → 네트워크 설정 → 볼륨 마운트 → PID 1 프로세스 시작을 순서대로 밟습니다. 이 흐름을 단계로 알면 "왜 안 뜨지", "왜 바로 죽지"를 어느 단계에서 끊겼는지로 좁힐 수 있습니다. docker run은 단순히 "이미지를 켜는 것"이 아니라 아래 6단계의 결과입니다.

[호스트]  docker run -d -p 8080:80 --name web nginx
   │
   ① 이미지 확인        로컬에 nginx 있나? → 없으면 레지스트리에서 pull
   │
   ② 쓰기 레이어 생성    읽기전용 이미지 위에 얇은 쓰기 레이어(RW)를 얹어 컨테이너 생성
   │
   ③ 네트워크 설정      새 net namespace + veth 쌍 → docker0 브리지 연결 → IP 할당
   │                    -p 8080:80 은 iptables NAT로 호스트 8080 → 컨테이너 80 매핑
   │
   ④ 볼륨·마운트        -v / --mount 로 지정한 볼륨을 컨테이너 파일시스템에 연결
   │
   ⑤ PID 1 시작        ENTRYPOINT + CMD 를 새 PID namespace 안의 PID 1로 exec
   │
   ⑥ 실행 유지         PID 1이 살아있으면 Running, 끝나면 컨테이너도 종료
   ▼
[결과]  docker ps 에 web (Up) — 실패하면 이 단계 전에 끊긴다

각 단계에서 무슨 일이 일어나고, 막히면 어떤 증상인가:

즉 "컨테이너가 떴다"는 ①~⑥이 모두 통과했다는 뜻입니다. 안 뜰 때는 에러 메시지로 단계를 좁힙니다 — Unable to find image·pull access denied는 ①, port is already allocated는 ③, executable file not found는 ⑤, docker ps엔 없고 docker ps -a에 Exited면 ⑥입니다. 특히 ⑥의 Exited (0)은 에러가 아니라 "PID 1이 할 일을 마치고 정상 종료"라는 뜻이라 docker logs에 오류가 없습니다 — 이때는 포그라운드로 계속 살아있을 프로세스(nginx, sleep infinity)나 -it 셸이 필요합니다.

docker run 명령은 옵션 하나가 빠지면 전혀 다른 상황이 펼쳐집니다. -d 없이 실행하면 터미널이 점유되어 Ctrl+C로 서비스를 끄는 실수를 하고, --name 없이 실행하면 컨테이너 ID나 무작위 이름을 외워야 합니다. -p 없이 실행하면 서비스가 외부에서 접근되지 않아 왜 연결이 안 되는지 찾아 헤매게 됩니다. 각 옵션이 없을 때 어떤 상황이 되는지를 먼저 이해하면, 왜 이 옵션들이 거의 항상 함께 쓰이는지 자연스럽게 납득됩니다. 이 ConceptBlock에서는 실무에서 가장 자주 사용하는 docker run 옵션과 그 의미를 다룹니다.

확대

가장 자주 쓰는 옵션들

-d (detached, 백그라운드 실행)

# 포어그라운드 실행 — 터미널 점유, Ctrl+C로 종료
docker run nginx

# 백그라운드 실행 — 컨테이너 ID만 출력하고 프롬프트 반환
docker run -d nginx
# a3f4b1c2d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5  ← 컨테이너 ID

-p (포트 바인딩)

# 형식: -p 호스트포트:컨테이너포트
docker run -d -p 8080:80 nginx
# 브라우저에서 http://localhost:8080 접속 → 컨테이너의 80포트

# 여러 포트 바인딩
docker run -d -p 8080:80 -p 8443:443 nginx

# 특정 IP에만 바인딩 (보안)
docker run -d -p 127.0.0.1:8080:80 nginx
# 로컬호스트에서만 접근 가능, 외부 접근 차단

# 호스트 포트를 지정하지 않으면 랜덤 포트
docker run -d -p 80 nginx
docker port <container_id>  # 할당된 포트 확인

--name (컨테이너 이름 지정)

# 이름 없이 실행 — Docker가 무작위 이름 생성
docker run -d nginx
# 이름: "romantic_turing" 같은 무작위 이름 → 관리하기 어려움

# 이름 지정 — 이름으로 참조 가능
docker run -d --name web-server nginx

# 이름으로 조작 가능
docker stop web-server
docker start web-server
docker logs web-server
docker exec -it web-server bash

-e (환경변수)

# 환경변수 설정
docker run -d \
  --name db \
  -e POSTGRES_PASSWORD=mysecret \
  -e POSTGRES_USER=appuser \
  -e POSTGRES_DB=mydb \
  postgres:15

# .env 파일에서 읽기
docker run -d --env-file .env myapp:latest

-v (볼륨, 데이터 영구 보존)

# 컨테이너 내부 데이터는 컨테이너 삭제 시 사라짐
# 볼륨 마운트로 영구 보존

# Named Volume (Docker가 관리)
docker run -d -v db-data:/var/lib/postgresql/data postgres:15

# Bind Mount (호스트 경로 직접 마운트)
docker run -d -v /home/user/myapp:/app myapp:latest
# 호스트 /home/user/myapp ↔ 컨테이너 /app 동기화

--rm (실행 후 자동 삭제)

# 일회성 명령 실행 후 자동 정리
docker run --rm ubuntu:22.04 echo "Hello, World!"
docker run --rm python:3.11 python -c "import sys; print(sys.version)"

# --rm 없이 실행하면 컨테이너가 Exited 상태로 남아있음
docker run ubuntu:22.04 echo "Hello"
docker ps -a  # Exited 상태 컨테이너 확인

-it (인터랙티브 + 터미널)

# 컨테이너 안에서 직접 명령 실행 (쉘 접속)
docker run -it ubuntu:22.04 bash
# 컨테이너 쉘 프롬프트가 열림
# root@a3f4b1c2:/# ls /
# root@a3f4b1c2:/# apt-get update
# exit 또는 Ctrl+D로 나옴

# 실행 중인 컨테이너에 접속
docker exec -it web-server bash

컨테이너를 실행한 후에는 상태 확인, 로그 조회, 내부 접속 세 가지 동작이 가장 자주 필요합니다. ps, logs, exec는 이 세 가지를 담당하는 기본 진단 명령어입니다.

확대

# 실행 중인 컨테이너 목록
docker ps

# 모든 컨테이너 (정지된 것 포함)
docker ps -a

# 컨테이너 로그 확인
docker logs web-server

# 실시간 로그 스트리밍 (tail -f처럼)
docker logs -f web-server

# 최근 50줄만
docker logs --tail 50 web-server

# 실행 중인 컨테이너 내부에서 명령 실행
docker exec web-server ls /etc/nginx
docker exec -it web-server bash  # 인터랙티브 쉘

# 컨테이너 상세 정보 (IP, 포트, 환경변수, 마운트 등)
docker inspect web-server

# 컨테이너 리소스 사용량 실시간 모니터링
docker stats

컨테이너 정지(stop/kill)와 상태 전환(start/rm)은 다음 모듈(컨테이너 생명주기)에서 자세히 다룹니다.

docker run이 '가벼운 VM을 하나 띄운다'고 이해하면, 정작 신호(signal) 처리·좀비 프로세스·자원 제한에서 예상 못 한 동작을 만납니다. 컨테이너는 별도 OS가 아니라 호스트 커널을 공유하는, 격리된 하나의 프로세스입니다. 그 '격리'가 어떻게 만들어지는지 알아야 컨테이너의 한계와 함정이 보입니다.

• 네임스페이스(namespace) = 격리: docker run은 새 PID·NET·MNT·UTS·IPC 네임스페이스를 만들어 프로세스에 '격리된 시야'를 줍니다. 그래서 컨테이너 안에서 ps를 하면 자기 프로세스만 보이고(PID 네임스페이스), 자기 네트워크 인터페이스만 보이며(NET 네임스페이스), 자기 파일시스템만 보입니다(MNT 네임스페이스). 하지만 커널은 호스트와 공유합니다 — 그래서 VM보다 가볍고, 대신 호스트 커널 버전에 종속됩니다.
• cgroup = 제한: --memory·--cpus는 네임스페이스가 아니라 cgroup으로 걸립니다. '무엇이 보이는가(격리)'와 '얼마나 쓸 수 있는가(제한)'는 서로 다른 축입니다.
• PID 1의 특수성: 컨테이너의 첫 프로세스는 그 PID 네임스페이스 안에서 PID 1로 뜹니다. 리눅스에서 PID 1은 특별합니다 — (1) 신호 핸들러를 직접 등록하지 않으면 SIGTERM 같은 기본 종료 신호가 무시되고, (2) 부모를 잃은 고아 프로세스를 거둬들이는(reap) 책임을 집니다. 앱을 아무 준비 없이 PID 1로 띄우면 graceful shutdown이 안 되고 좀비 프로세스가 쌓일 수 있습니다.

즉 컨테이너를 '작은 VM'이 아니라 '네임스페이스로 격리되고 cgroup으로 제한된 프로세스'로 이해해야, docker stop이 왜 신호를 보내는지·왜 PID 1 설계가 중요한지가 한 번에 이어집니다.