Docker 입문

Docker 입문 — 컨테이너·이미지·Compose 한 번에 정리. "내 컴퓨터에선 됐는데"라는 말이 사라지는 이유가 Docker다. 컨테이너가 무엇인지부터 이미지 만들기(Dockerfile), 여러 컨테이너를 묶는 docker compose까지, 실제 명령과 출력을 함께 정리한다.

---

들어가며

새 팀원이 들어왔다. 프로젝트를 받아 실행하려는데, Node 버전이 안 맞고, 로컬 PostgreSQL이 없고, 환경 변수가 빠졌다. 반나절을 환경 세팅에 쓴다. 그리고 막상 배포하면 또 터진다 — "제 컴퓨터에선 됐는데요."

이 고질적인 문제를 거의 사라지게 만든 도구가 Docker다. 애플리케이션을 그 실행 환경(OS 라이브러리, 런타임, 의존성, 설정)까지 통째로 컨테이너(container)라는 상자에 담아, 어디서든 똑같이 실행되게 한다. 개발자 PC, 동료 PC, 운영 서버에서 같은 상자가 같은 방식으로 돈다.

Docker의 핵심 한 줄: 애플리케이션과 그 실행 환경을 하나로 묶어, 어디서나 동일하게 실행한다. 환경이 코드가 되는 순간, "내 컴퓨터에선 됐는데"가 사라진다.

이 글에서는 컨테이너가 무엇인지(가상 머신과 무엇이 다른지)부터 시작해, 이미지·컨테이너·레지스트리 개념을 잡고, Dockerfile로 직접 이미지를 만들고, 볼륨·네트워크를 다루고, 마지막으로 docker compose로 여러 컨테이너를 한 번에 띄우는 데까지 간다. 모든 명령은 실제 출력과 함께 본다.

---

1. Docker란 무엇인가 — 컨테이너의 개념

컨테이너는 호스트 OS 위에서 격리되어 도는 하나의 프로세스 묶음이다. 자기만의 파일 시스템, 네트워크, 프로세스 공간을 갖지만, 그 아래 운영체제 커널은 호스트와 공유한다. 이 "커널 공유"가 가상 머신(VM)과의 결정적 차이다.

가상 머신은 하이퍼바이저 위에 앱마다 게스트 OS를 통째로 올린다. 그래서 무겁고(수 GB), 부팅도 수십 초 걸린다. 반면 컨테이너는 게스트 OS 없이 호스트 커널을 함께 쓰므로, 크기는 수십~수백 MB에 시작은 보통 1초 안쪽이다.

정리하면, 컨테이너는 "VM만큼 격리되면서 프로세스만큼 가벼운" 절충점이다. 그래서 한 서버에 수십 개를 띄우고, 초 단위로 켜고 끄고, 똑같은 복제본을 무한정 찍어낼 수 있다. 이 특성이 마이크로서비스·CI/CD·오토스케일링을 가능하게 한 토대다.

---

2. 핵심 개념 — 이미지, 컨테이너, 레지스트리

Docker를 이해하려면 세 단어만 잡으면 된다.

• 이미지(Image) — 실행에 필요한 모든 것(베이스 OS, 런타임, 코드, 의존성, 설정)을 담은 읽기 전용 템플릿. 한 번 만들면 변하지 않는다.
• 컨테이너(Container) — 이미지를 실행한 인스턴스. 같은 이미지로 컨테이너를 여러 개 띄울 수 있고, 각자 독립적으로 돌며, 삭제하면 사라진다.
• 레지스트리(Registry) — 이미지를 저장·공유하는 저장소. 공개 레지스트리가 Docker Hub이고, nginx·postgres 같은 공식 이미지를 여기서 받는다(docker pull).

객체지향에 빗대면 이미지는 클래스, 컨테이너는 인스턴스다. 클래스 하나로 객체를 여러 개 찍어내듯, 이미지 하나로 컨테이너를 여러 개 만든다. 요리에 빗대면 이미지는 레시피, 컨테이너는 그 레시피로 만든 요리다.

---

3. 설치하고 첫 컨테이너 실행하기

설치는 운영체제별 Docker Desktop(Windows·macOS) 또는 Docker Engine(Linux)으로 한다. 설치되면 가장 먼저 동작 확인을 한다.

docker run hello-world

Hello from Docker!
This message shows that your installation appears to be working correctly.
...

이제 진짜 서버 하나를 띄워보자. 웹 서버 nginx를 백그라운드로 실행한다.

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

Unable to find image 'nginx:latest' locally
latest: Pulling from library/nginx
... Pull complete
Status: Downloaded newer image for nginx:latest
9c2f3a1be1a3f0c8d4b7e6a5c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0

옵션의 의미는 이렇다.

• -d (detached) — 백그라운드로 실행. 터미널을 점유하지 않는다.
• -p 8080:80 — 호스트의 8080 포트를 컨테이너의 80 포트로 연결. 브라우저에서 localhost:8080으로 접속하면 컨테이너 안 nginx가 응답한다.
• --name web — 컨테이너에 이름 부여. 이후 명령에서 이 이름으로 가리킨다.

로컬에 이미지가 없으면 Docker Hub에서 자동으로 받아온다(Unable to find ... locally → Pulling). 실행 중인 컨테이너를 확인한다.

docker ps

CONTAINER ID   IMAGE     COMMAND                  STATUS         PORTS                  NAMES
9c2f3a1be1a3   nginx     "/docker-entrypoint.…"   Up 5 seconds   0.0.0.0:8080->80/tcp   web

자주 쓰는 기본 명령은 다음과 같다.

docker images                 # 로컬에 받아둔 이미지 목록
docker logs web               # 컨테이너 web의 로그 보기
docker exec -it web bash      # 실행 중인 컨테이너 안으로 셸 진입
docker stop web               # 컨테이너 중지
docker rm web                 # 중지된 컨테이너 삭제
docker rmi nginx              # 이미지 삭제

여기서 중요한 감각 하나. 컨테이너는 언제든 버릴 수 있는 일회용이라는 점이다. 문제가 생기면 고치기보다 지우고 다시 띄운다. 이 "지우고 다시 만든다"가 Docker 운영의 기본 태도다.

---

4. 이미지 직접 만들기 — Dockerfile

남이 만든 이미지를 받아 쓰는 걸 넘어, 내 애플리케이션을 이미지로 만들어야 진짜 시작이다. 그 설계도가 Dockerfile이다. 프로젝트 루트에 Dockerfile이라는 파일을 만들고 명령을 위에서 아래로 적는다.

# 1. 베이스 이미지 — Node.js 20 (가벼운 alpine 버전)
FROM node:20-alpine

# 2. 컨테이너 안에서 작업할 디렉터리
WORKDIR /app

# 3. 의존성 정의 파일부터 복사 (캐시 최적화 — 아래 설명)
COPY package*.json ./
RUN npm install

# 4. 나머지 소스 코드 복사
COPY . .

# 5. 앱이 사용하는 포트 (문서화 목적)
EXPOSE 3000

# 6. 컨테이너가 시작될 때 실행할 명령
CMD ["npm", "start"]

주요 명령어의 역할은 이렇다.

• FROM — 출발점이 되는 베이스 이미지. 모든 Dockerfile은 여기서 시작한다.
• WORKDIR — 이후 명령이 실행될 작업 디렉터리.
• COPY — 호스트의 파일을 이미지 안으로 복사.
• RUN — 이미지를 만드는 시점에 실행할 명령(의존성 설치 등).
• EXPOSE — 컨테이너가 사용하는 포트를 명시(실제 개방은 -p로).
• CMD — 컨테이너가 시작될 때 실행할 기본 명령.

작성했으면 빌드한다. -t로 이름(태그)을 붙이고, 마지막 .은 빌드 컨텍스트(현재 폴더)다.

docker build -t myapp:1.0 .

[+] Building 12.3s (10/10) FINISHED
 => [internal] load build definition from Dockerfile
 => [1/4] FROM docker.io/library/node:20-alpine
 => [2/4] WORKDIR /app
 => [3/4] COPY package*.json ./
 => [4/4] RUN npm install
 => exporting to image
 => => naming to docker.io/library/myapp:1.0

빌드가 끝나면 docker run -d -p 8080:3000 myapp:1.0으로 내 앱 컨테이너를 띄울 수 있다.

레이어와 캐시 — COPY 순서가 중요한 이유

Dockerfile의 각 명령은 레이어(layer) 하나를 만든다. 이미지는 이 레이어들이 쌓인 결과물이고, Docker는 바뀌지 않은 레이어는 캐시해서 재사용한다. 그래서 위 예제에서 package*.json을 먼저 복사하고 npm install을 한 뒤, 나머지 소스를 나중에 복사했다. 소스 코드만 고치고 의존성은 그대로일 때, npm install 레이어가 캐시에 적중해 빌드가 몇 초로 끝나기 때문이다. 순서를 반대로 하면 코드 한 줄만 바꿔도 매번 의존성을 새로 설치한다.

빌드 컨텍스트에서 불필요한 파일(예: node_modules, .git, .env)을 빼려면 .dockerignore를 둔다. 빌드가 빨라지고, 비밀 값이 이미지에 섞여 들어가는 사고도 막는다.

node_modules
.git
.env
*.log

---

5. 데이터와 통신 — 볼륨과 네트워크

볼륨 — 사라지지 않는 데이터

컨테이너는 일회용이라, 삭제하면 그 안의 데이터도 함께 사라진다. DB를 컨테이너로 띄웠다가 컨테이너를 지우면 데이터가 날아간다는 뜻이다. 이를 막으려고 데이터를 컨테이너 바깥에 보관하는 장치가 볼륨(volume)이다.

# Docker가 관리하는 named volume 생성 후 연결
docker volume create pgdata
docker run -d --name db -v pgdata:/var/lib/postgresql/data postgres:17

-v pgdata:/var/lib/postgresql/data는 컨테이너 안 PostgreSQL 데이터 경로를 볼륨에 연결한다. 이제 컨테이너를 지우고 다시 만들어도 데이터는 볼륨에 남아 있다. (호스트의 특정 폴더를 직접 연결하는 bind mount -v $(pwd)/data:/... 방식도 있다.)

네트워크 — 컨테이너끼리 대화하기

기본적으로 컨테이너는 격리돼 있다. 같은 사용자 정의 네트워크에 묶으면, 서로의 컨테이너 이름을 호스트명처럼 써서 통신할 수 있다.

docker network create app-net
docker run -d --name db   --network app-net postgres:17
docker run -d --name web  --network app-net myapp:1.0

이제 web 컨테이너 안에서는 DB 주소를 IP가 아니라 그냥 db라는 이름으로 접속할 수 있다(postgres://user@db:5432/...). 이름 기반 통신이 가능해지는 게 핵심이다.

그런데 컨테이너가 두세 개로 늘면 이 run 명령들을 매번 순서 맞춰 치는 게 번거로워진다. 여기서 Compose가 등장한다.

---

6. 여러 컨테이너 한 번에 — Docker Compose

실제 애플리케이션은 보통 여러 컨테이너의 묶음이다. 웹 앱 + DB + 캐시(Redis)처럼. 이걸 docker run으로 하나씩 띄우려면 네트워크 만들고, 볼륨 만들고, 순서 맞춰 실행하고… 금세 복잡해진다. Docker Compose는 이 전체 구성을 YAML 파일 하나로 정의하고, 명령 한 번으로 전부 띄운다.

프로젝트 루트에 compose.yml(또는 docker-compose.yml)을 만든다.

# compose.yml
services:
  web:
    build: .                       # 현재 폴더의 Dockerfile로 빌드
    ports:
      - "8080:3000"                # 호스트 8080 → 컨테이너 3000
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/app
    depends_on:
      - db
      - cache

  db:
    image: postgres:17
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: app
    volumes:
      - db-data:/var/lib/postgresql/data   # 데이터 영속화

  cache:
    image: redis:7

volumes:
  db-data:

읽는 법은 직관적이다. services 아래 컨테이너 셋(web, db, cache)을 정의했고, web은 환경 변수에서 DB 주소를 db라는 서비스 이름으로 가리킨다(Compose가 같은 네트워크에 묶어주기 때문에 이름으로 접속된다). depends_on으로 시작 순서를, volumes로 DB 데이터 영속화를 선언했다.

이제 명령 한 번으로 전부 띄운다.

docker compose up -d

[+] Running 4/4
 ✔ Network app_default     Created
 ✔ Container app-db-1      Started
 ✔ Container app-cache-1   Started
 ✔ Container app-web-1     Started

상태 확인·로그·종료도 한 곳에서 한다.

docker compose ps        # 이 프로젝트의 컨테이너 상태
docker compose logs -f   # 전체 로그 실시간 확인
docker compose down      # 전부 중지하고 정리 (볼륨은 기본 유지)

흔한 함정 — 오래된 튜토리얼 주의. 예전 자료는 파일 맨 위에 version: "3.8"을 적고, 명령은 docker-compose(하이픈)를 썼다. 둘 다 옛 방식이다. 지금의 Compose V2에서 version 필드는 obsolete라 그냥 빼야 하고(넣으면 경고가 뜬다), 명령도 docker compose(띄어쓰기)가 표준이다. 하이픈 버전(docker-compose)은 더 이상 유지되지 않는다.

---

7. 한 단계 더 — 멀티스테이지 빌드와 명령어 정리

이미지가 무거우면 배포가 느리고 보안 표면도 넓어진다. 멀티스테이지 빌드는 빌드용 단계와 실행용 단계를 나눠, 최종 이미지에는 결과물만 담는 기법이다. 빌드 도구는 버리고 산출물만 남긴다.

# 1단계: 빌드 (무거운 빌드 도구 포함)
FROM node:20 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# 2단계: 실행 (결과물만 복사 → 최종 이미지는 가벼움)
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY package*.json ./
RUN npm install --omit=dev
CMD ["node", "dist/index.js"]

COPY --from=builder가 핵심이다. 1단계에서 만든 산출물(dist)만 2단계로 가져오고, 무거운 빌드 의존성은 최종 이미지에 포함되지 않는다.

마지막으로 자주 쓰는 명령을 한 표로 정리한다.

명령어	하는 일
docker ps / docker ps -a	실행 중 / 전체(멈춘 것 포함) 컨테이너 목록
docker images	로컬 이미지 목록
docker build -t 이름:태그 .	Dockerfile로 이미지 빌드
docker run -d -p 8080:80 이미지	컨테이너 백그라운드 실행 + 포트 연결
docker logs -f 이름	컨테이너 로그 실시간 확인
docker exec -it 이름 sh	실행 중인 컨테이너 안 셸 진입
docker stop / rm 이름	컨테이너 중지 / 삭제
docker compose up -d	Compose에 정의된 서비스 전부 실행
docker compose down	전부 중지하고 정리

---

마치며

Docker는 "애플리케이션과 그 실행 환경을 하나로 묶는다"는 단순한 발상에서 출발한다. 그 묶음이 이미지이고, 이미지를 실행한 게 컨테이너이며, Dockerfile로 이미지를 만들고 docker compose로 여러 컨테이너를 한 번에 띄운다. 이 모델 위에서 "내 컴퓨터에선 됐는데"가 사라지고, 배포와 협업이 단순해진다.

핵심만 다시 짚으면, 이미지(템플릿) → 컨테이너(실행) → Compose(묶음) 의 흐름과, 데이터는 볼륨으로 살리고, 컨테이너는 이름으로 통신한다는 두 가지다. 여기까지 잡으면 남이 만든 이미지를 가져다 쓰는 단계를 넘어, 내 서비스를 컨테이너로 패키징하고 운영하는 출발선에 선 것이다.

다음 단계는 이 이미지를 자동으로 빌드·배포하는 CI/CD, 그리고 컨테이너를 여러 서버에 걸쳐 운영하는 오케스트레이션(Kubernetes)이다. 그건 별도 글에서 이어가겠다.

---

참고 출처

• Docker Docs — Get started — https://docs.docker.com/get-started/
• Docker Docs — Dockerfile reference — https://docs.docker.com/reference/dockerfile/
• Docker Docs — Docker Compose — https://docs.docker.com/compose/
• Docker Docs — Compose file reference — https://docs.docker.com/reference/compose-file/
• Docker Docs — Volumes — https://docs.docker.com/engine/storage/volumes/
• Docker — Logo, Icon, and Brand Guidelines — https://www.docker.com/company/newsroom/media-resources/

Docker 및 Docker 로고(Moby Dock 고래)는 Docker, Inc.의 상표이며, 본 글에서는 식별·설명 목적으로만 사용했습니다.