도커와 컨테이너: 어디서나 똑같이 실행하기

"내 컴퓨터에서는 되는데요"를 끝내는 도커와 컨테이너를 배워요. 컨테이너가 가상 머신과 어떻게 다른지, 이미지와 레이어와 컨테이너의 관계를 이해하고, Dockerfile의 순서 하나로 다시 빌드하는 시간이 61초에서 1초로 줄어드는 레이어 캐시를 직접 흉내 내 확인해요. .dockerignore로 비밀 파일을 빼는 법, 지운 비밀이 이미지 층에 그대로 남는 함정, 컨테이너를 지우면 사라지는 데이터와 볼륨, 컨테이너 안의 서버를 0.0.0.0으로 열어야 하는 이유, 앱과 데이터베이스를 함께 띄우는 docker compose까지 다뤄요.

중급강의 4 / 6약 15분

앞 강의에서 앱 서버를 여러 대 띄우면 좋다고 했어요. 그런데 서버마다 파이썬 버전, 라이브러리 버전, 운영체제 설정이 조금씩 다르면 어떻게 될까요? 개발자 컴퓨터에서는 잘 되던 프로그램이 서버에서는 오류를 내는 일, "내 컴퓨터에서는 되는데요"가 여기서 생겨요. 도커는 프로그램과 그 프로그램이 돌아가는 데 필요한 모든 것(운영체제의 파일, 언어, 라이브러리, 설정)을 이미지라는 상자 하나에 담아, 어디서든 똑같이 실행하게 해 줘요.

컨테이너는 가벼운 상자예요

구분가상 머신컨테이너
무엇을 담나운영체제 전체(커널 포함)프로그램과 필요한 파일만. 커널은 바깥 운영체제와 나눠 써요
크기수 GB수십에서 수백 MB
켜는 시간수십 초에서 몇 분대개 1초 안팎
격리아주 강해요강하지만 커널을 나눠 쓰는 만큼 가상 머신보다는 약해요

컨테이너는 운영체제의 기능으로 "이 프로그램에게는 이 파일들과 이 네트워크만 보이게" 칸막이를 친 거예요. 그래서 가볍고 빨라요. 리눅스의 기능을 쓰기 때문에, 윈도와 맥의 Docker Desktop은 안에 작은 리눅스 가상 머신을 하나 두고 그 위에서 컨테이너를 돌려요(윈도는 WSL2를 써요). Docker Desktop은 개인과 작은 회사, 교육 목적이면 무료로 쓸 수 있어요.

세 가지 말을 구별해 두면 나머지가 쉬워요.

  • 이미지: 프로그램과 실행 환경을 담은 읽기 전용 상자예요. 한 번 만들면 바뀌지 않아요.
  • 컨테이너: 이미지를 실행한 것이에요. 이미지 하나로 컨테이너를 여러 개 띄울 수 있어요. 클래스와 객체의 관계와 비슷해요.
  • Dockerfile: 이미지를 만드는 조리법이에요.

Dockerfile: 이미지를 만드는 조리법

첫 강의의 할 일 API를 Flask로 만들었다고 해 볼게요. 이런 Dockerfile을 써요.

# 바탕: 파이썬 3.12가 든 작은 리눅스
FROM python:3.12-slim

# 이후 명령을 실행할 폴더
WORKDIR /app

# 라이브러리 목록을 먼저 복사해 설치하고, 그다음에 코드를 복사해요
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

# 관리자가 아닌 사용자로 실행해요
RUN useradd --create-home appuser
USER appuser

EXPOSE 8000
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "app:app"]

Dockerfile의 주석은 이렇게 줄 맨 앞에만 쓸 수 있어요. 명령 뒤에 #을 붙이면 주석이 아니라 명령의 일부로 읽혀서 오류가 나요.

$ docker build -t todo-api:1.0 .                          # 이미지 만들기
$ docker run --rm -p 8000:8000 --env-file .env todo-api:1.0  # 컨테이너 실행
$ docker ps                                               # 실행 중인 컨테이너 보기
$ docker logs -f 컨테이너이름                               # 기록 보기
$ docker exec -it 컨테이너이름 sh                           # 컨테이너 안에 들어가 보기
  • FROM은 바탕 이미지예요. latest가 아니라 3.12-slim처럼 버전을 정해 두면 언제 만들어도 같은 환경이 나와요. slim은 꼭 필요한 것만 남긴 작은 버전이에요.
  • -p 8000:8000은 "내 컴퓨터의 8000번으로 온 연결을 컨테이너의 8000번으로 넘겨라"라는 뜻이에요.
  • --env-file .env로 비밀번호 같은 설정을 실행할 때 넣어요. 이미지 안에는 넣지 않아요. 그 이유는 조금 뒤에 봐요.
  • CMD를 ["gunicorn", ...]처럼 목록으로 쓰면, 도커가 보내는 "그만 멈춰라" 신호를 프로그램이 바로 받아 깔끔하게 끝날 수 있어요.

컨테이너 안의 서버는 0.0.0.0으로

첫 강의에서 127.0.0.1로 연 서버는 그 컴퓨터 안에서만 접속할 수 있다고 했어요. 컨테이너는 자기만의 네트워크를 가진 작은 컴퓨터 같아서, 컨테이너 안에서 127.0.0.1로 열면 컨테이너 자신만 접속할 수 있어요. -p로 포트를 연결해도 바깥에서는 접속이 안 돼요. 그래서 위의 CMD처럼 0.0.0.0으로 열어요. 컨테이너를 처음 다룰 때 가장 흔히 막히는 곳이에요.

레이어와 캐시: 순서가 빌드 시간을 정해요

이미지는 Dockerfile의 명령마다 하나씩 쌓인 층(레이어)으로 이뤄져요. 도커는 각 층을 기억해 두었다가, 명령과 복사하는 파일의 내용이 그대로면 다시 실행하지 않고 저장해 둔 층을 써요. 단, 어떤 층이 바뀌면 그 위의 층은 모두 다시 만들어요. 이 규칙을 흉내 내서, 같은 일을 하는 두 Dockerfile의 다시 빌드 시간을 비교해 볼게요. 라이브러리 설치(pip install)는 60초 걸린다고 칠게요.

import hashlib
from fnmatch import fnmatch

COST = {"FROM": 5, "COPY": 1, "RUN": 60, "CMD": 0}     # 단계마다 걸린다고 치는 초

def build(dockerfile, files, cache):
    key, spent, lines = "", 0, []
    for kind, arg in dockerfile:
        content = ""
        if kind == "COPY":                              # 복사하는 파일의 내용까지 열쇠에 넣어요
            content = "".join(f"{n}={files[n]};" for n in sorted(files) if fnmatch(n, arg))
        key = hashlib.sha256(f"{key}|{kind} {arg}|{content}".encode()).hexdigest()
        if key in cache:
            lines.append(f"  {kind} {arg}: 캐시")
        else:
            cache.add(key)
            spent += COST[kind]
            lines.append(f"  {kind} {arg}: 새로 실행 {COST[kind]}초")
    return spent, lines

bad = [("FROM", "python:3.12-slim"), ("COPY", "*"), ("RUN", "pip install -r requirements.txt"), ("CMD", "python app.py")]
good = [("FROM", "python:3.12-slim"), ("COPY", "requirements.txt"), ("RUN", "pip install -r requirements.txt"),
        ("COPY", "*"), ("CMD", "python app.py")]

for name, dockerfile in (("코드를 먼저 복사", bad), ("요구 사항을 먼저 복사", good)):
    cache = set()
    files = {"requirements.txt": "flask==3.1.0", "app.py": "print('v1')"}
    first, _ = build(dockerfile, files, cache)
    files["app.py"] = "print('v2')"                      # 코드 한 줄만 고쳤어요
    second, lines = build(dockerfile, files, cache)
    print(f"[{name}] 처음 {first}초, 코드만 고친 뒤 다시 {second}초")
    print("\n".join(lines))
[코드를 먼저 복사] 처음 66초, 코드만 고친 뒤 다시 61초
  FROM python:3.12-slim: 캐시
  COPY *: 새로 실행 1초
  RUN pip install -r requirements.txt: 새로 실행 60초
  CMD python app.py: 새로 실행 0초
[요구 사항을 먼저 복사] 처음 67초, 코드만 고친 뒤 다시 1초
  FROM python:3.12-slim: 캐시
  COPY requirements.txt: 캐시
  RUN pip install -r requirements.txt: 캐시
  COPY *: 새로 실행 1초
  CMD python app.py: 새로 실행 0초

코드를 먼저 복사하면 app.py 한 줄만 고쳐도 복사 층이 바뀌고, 그 위의 라이브러리 설치를 다시 해서 61초가 걸려요. 라이브러리 목록을 먼저 복사해 설치하고 코드를 나중에 복사하면, 목록이 그대로인 한 설치 층은 캐시를 써서 1초면 끝나요. 하루에 수십 번 빌드하면 큰 차이예요. 규칙은 하나예요. 자주 바뀌는 것일수록 아래쪽(나중)에 둬요.

.dockerignore: 보내지 않을 파일

COPY . .은 폴더의 모든 파일을 복사해요. 거기에는 비밀번호가 든 .env, 커다란 .git 기록, 내 컴퓨터의 node_modules, 테스트용 데이터베이스까지 들어 있어요. .dockerignore 파일에 빼고 싶은 것을 적어 둬요.

context = ["app.py", "requirements.txt", ".env", ".git/config", "node_modules/left-pad/index.js",
           "data/users.db", "tests/test_app.py", "README.md"]
dockerignore = [".env", ".git", ".git/*", "node_modules", "node_modules/*", "*.db", "data/*", "tests/*"]

sent = [f for f in context if not any(fnmatch(f, pattern) for pattern in dockerignore)]
print("이미지 만들 때 보내는 파일:", sent)
print("빠진 파일:", sorted(set(context) - set(sent)))
이미지 만들 때 보내는 파일: ['app.py', 'requirements.txt', 'README.md']
빠진 파일: ['.env', '.git/config', 'data/users.db', 'node_modules/left-pad/index.js', 'tests/test_app.py']

이미지가 작아지고 빌드가 빨라지는 것도 좋지만, 가장 중요한 건 비밀이 이미지에 들어가지 않는다는 점이에요. 이미지는 저장소에 올리고 여러 서버가 내려받아 쓰는 물건이라, 안에 든 것은 누군가 언젠가 열어 볼 수 있다고 생각해야 해요.

지운 비밀도 이미지에 남아요

".env를 복사했다가 다음 줄에서 지우면 되지 않나?"라고 생각할 수 있어요. 층의 원리를 떠올리면 왜 안 되는지 보여요.

layers = [
    ("FROM python:3.12-slim", {"/usr/bin/python3": "..."}),
    ("COPY . .", {"/app/app.py": "print('hi')", "/app/.env": "API_KEY=sk-secret-123"}),
    ("RUN rm .env", {"/app/.env": None}),                # None: 이 층에서 지웠다는 표시
]

def final_view(layers):
    files = {}
    for _, change in layers:
        for path, value in change.items():
            if value is None:
                files.pop(path, None)
            else:
                files[path] = value
    return files

print("컨테이너 안에서 보이는 파일:", sorted(final_view(layers)))
leaked = [(step, change["/app/.env"]) for step, change in layers if change.get("/app/.env")]
print("하지만 층을 하나씩 열어 보면:", leaked)
컨테이너 안에서 보이는 파일: ['/app/app.py', '/usr/bin/python3']
하지만 층을 하나씩 열어 보면: [('COPY . .', 'API_KEY=sk-secret-123')]

층은 바뀌지 않아요. 지우기는 위에 "이 파일은 없는 것으로 친다"는 층을 하나 더 얹는 것일 뿐이라, 아래층에는 비밀이 그대로 남아요. 이미지를 받은 사람은 층을 풀어서 꺼낼 수 있어요. 비밀은 처음부터 이미지에 넣지 않고, 실행할 때 환경 변수(--env-file)나 비밀 관리 기능으로 넣어요. 실수로 비밀이 든 이미지를 올렸다면 이미지를 지우는 것으로 끝내지 말고, 그 비밀(키, 비밀번호)을 바로 바꿔야 해요.

컨테이너를 지우면 데이터도 사라져요

컨테이너가 실행 중에 쓴 파일은 그 컨테이너만의 쓰기 층에 저장돼요. 새 버전으로 바꾸려고 컨테이너를 지우고 다시 만들면 그 층도 함께 사라져요.

class Container:
    def __init__(self, volume=None):
        self.writable = {}                                # 컨테이너마다 생기는 쓰기 층
        self.volume = volume                              # 바깥에 따로 둔 저장소(볼륨)

    def write(self, path, value):
        if self.volume is not None and path.startswith("/data/"):
            self.volume[path] = value
        else:
            self.writable[path] = value

    def read(self, path):
        if self.volume is not None and path.startswith("/data/"):
            return self.volume.get(path)
        return self.writable.get(path)

c1 = Container()
c1.write("/data/todos.db", "할 일 3개")
c1 = Container()                                         # 새 버전으로 바꾸려고 지우고 다시 만들었어요
print("볼륨 없이:", c1.read("/data/todos.db"))

volume = {}
c2 = Container(volume)
c2.write("/data/todos.db", "할 일 3개")
c2.write("/tmp/cache", "임시 파일")
c2 = Container(volume)
print("볼륨을 붙이면:", c2.read("/data/todos.db"), "| 볼륨 밖의 파일:", c2.read("/tmp/cache"))
볼륨 없이: None
볼륨을 붙이면: 할 일 3개 | 볼륨 밖의 파일: None

데이터베이스 파일처럼 남아야 하는 것은 볼륨에 둬요. 볼륨은 컨테이너 바깥에 따로 있는 저장소라, 컨테이너를 몇 번을 다시 만들어도 남아요(docker run -v todo-data:/data ...). 반대로 말하면 컨테이너 자체는 언제 지워도 괜찮게 만들어야 해요. 서버 트랙 첫 강의의 "서버는 기억하지 않는다"와 같은 생각이에요.

docker compose: 여러 컨테이너를 함께

실제 서비스는 앱, 데이터베이스, 앞단의 Nginx처럼 여러 컨테이너로 이뤄져요. 이걸 하나하나 명령으로 띄우는 대신 compose.yaml 파일에 적어 두고 한 번에 띄워요.

services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgresql://todo:${DB_PASSWORD}@db:5432/todo
    depends_on:
      db:
        condition: service_healthy      # 데이터베이스가 준비된 뒤에 시작해요
  db:
    image: postgres:17
    environment:
      POSTGRES_USER: todo
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: todo
    volumes:
      - db-data:/var/lib/postgresql/data  # 데이터는 볼륨에
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U todo"]
      interval: 5s
      retries: 5
volumes:
  db-data:
$ docker compose up -d        # 모두 띄우기(뒤에서 실행)
$ docker compose logs -f app  # 앱의 기록 보기
$ docker compose down         # 모두 멈추고 컨테이너 지우기(볼륨은 남아요)
  • 앱은 데이터베이스 주소를 db라는 서비스 이름으로 찾아요. compose가 같은 파일의 컨테이너끼리 이름으로 찾을 수 있게 작은 DNS를 만들어 줘요.
  • 비밀번호는 ${DB_PASSWORD}처럼 바깥(같은 폴더의 .env 파일이나 환경 변수)에서 받아요. 파일에 직접 적지 않아요.
  • 데이터베이스는 포트를 바깥에 열지 않았어요. 같은 compose 안의 앱만 접속할 수 있어요.
  • 새로 온 팀원도 이 파일 하나로 docker compose up 한 번이면 똑같은 개발 환경을 얻어요. "설치 방법" 문서가 실행할 수 있는 파일이 된 셈이에요.

좋은 이미지를 만드는 습관

  • 버전을 정해요. FROM python:3.12-slim처럼 정해 두고, 라이브러리도 requirements.txt에 버전을 적어요.
  • 작게 만들어요. slim 같은 작은 바탕 이미지를 쓰고, 빌드에만 필요한 도구는 최종 이미지에 남기지 않아요. 빌드하는 이미지와 실행하는 이미지를 나누는 다단계 빌드가 이럴 때 쓰여요.
  • 관리자로 실행하지 않아요. USER로 일반 사용자를 정하면, 앱에 구멍이 뚫려도 피해가 줄어요.
  • 하나의 컨테이너에는 하나의 일. 앱과 데이터베이스를 한 컨테이너에 넣지 않고 따로 띄워요. 따로 바꾸고, 따로 늘리고, 따로 다시 시작할 수 있어요.
  • 기록은 화면(표준 출력)으로. 파일 대신 화면에 찍으면 docker logs와 서버의 기록 수집 도구가 모아 줘요.

실습

  1. 레이어 캐시 예제에서 requirements.txt의 내용을 바꾸면 두 Dockerfile의 다시 빌드 시간은 각각 얼마인가요? 왜 그런가요?
  2. .dockerignore 예제에 *.log와 __pycache__를 더하고, 결과가 어떻게 바뀌는지 확인해 보세요.
  3. 층 예제에 RUN echo $API_KEY > /app/key.txt 같은 층을 더하면 무엇이 남을지 생각해 보세요. 실행할 때 환경 변수로만 넣으면 왜 안전한가요?
  4. 도커를 설치할 수 있다면, 첫 강의의 할 일 서버(표준 라이브러리 버전)를 담는 Dockerfile을 써서 실행해 보세요. 서버를 127.0.0.1로 열었을 때와 0.0.0.0으로 열었을 때 내 브라우저에서 접속되는지 비교해 보세요.
  5. compose 예제에 앞 강의의 Nginx를 proxy 서비스로 더하고, 앱의 포트는 바깥에 열지 않게 바꿔 보세요.

자주 하는 실수

  • latest 이미지를 쓴다. 언제 받느냐에 따라 다른 버전이 와요. 버전을 정해요.
  • 코드를 라이브러리 설치보다 먼저 복사한다. 코드 한 줄에 설치를 처음부터 다시 해요.
  • .dockerignore 없이 COPY . .을 쓴다. 비밀 파일과 쓸데없는 파일이 이미지에 들어가요.
  • 비밀을 이미지에 넣었다가 다음 층에서 지운다. 아래층에 그대로 남아요. 처음부터 넣지 않아요.
  • 컨테이너 안의 서버를 127.0.0.1로 연다. 바깥에서 접속이 안 돼요. 0.0.0.0으로 열어요.
  • 데이터를 컨테이너 안에만 둔다. 컨테이너를 지우면 사라져요. 볼륨을 써요.
  • 관리자 권한으로 실행한다. USER로 일반 사용자를 정해요.

점검 문제

  1. 컨테이너가 가상 머신보다 가볍고 빠른 이유는?
  2. 이미지와 컨테이너의 차이는?
  3. 컨테이너 안의 서버를 0.0.0.0으로 열어야 하는 이유는?
  4. Dockerfile에서 requirements.txt를 코드보다 먼저 복사하면 빌드가 빨라지는 이유는?
  5. .dockerignore에 .env를 꼭 넣어야 하는 이유는?
  6. 비밀 파일을 복사한 뒤 다음 명령에서 지워도 안전하지 않은 이유는?
  7. 데이터베이스 컨테이너에 볼륨을 붙이는 이유는?
  8. compose에서 앱이 데이터베이스를 db라는 이름으로 찾을 수 있는 이유는?

정답

  1. 운영체제 전체를 담지 않고, 바깥 운영체제의 커널을 나눠 쓰면서 프로그램과 필요한 파일만 칸막이 안에 두기 때문이에요.
  2. 이미지는 프로그램과 실행 환경을 담은 읽기 전용 상자이고, 컨테이너는 그 이미지를 실행한 것이에요. 이미지 하나로 컨테이너를 여러 개 띄울 수 있어요.
  3. 컨테이너는 자기만의 네트워크를 가져서, 안에서 127.0.0.1로 열면 컨테이너 자신만 접속할 수 있기 때문이에요.
  4. 도커는 층마다 캐시를 쓰는데, 바뀐 층의 위는 모두 다시 만들어요. 자주 안 바뀌는 라이브러리 목록과 설치를 아래에 두면, 코드만 고쳤을 때 설치 층은 캐시를 써요.
  5. 빼지 않으면 COPY . .으로 비밀번호가 이미지에 들어가고, 이미지는 저장소에 올라가 여러 곳에서 내려받아지기 때문이에요.
  6. 층은 바뀌지 않아서, 지우기는 위에 "없는 것으로 친다"는 층을 얹을 뿐 아래층에 비밀이 그대로 남기 때문이에요.
  7. 컨테이너를 지우면 그 안의 쓰기 층도 사라지는데, 볼륨은 컨테이너 바깥에 따로 있어서 컨테이너를 다시 만들어도 데이터가 남기 때문이에요.
  8. compose가 같은 파일의 컨테이너들을 위한 네트워크와 작은 DNS를 만들어, 서비스 이름으로 서로 찾게 해 주기 때문이에요.

다음 강의

이제 이미지 하나로 어디서나 똑같이 실행할 수 있어요. 남은 건 "누가, 언제" 빌드하고 배포하느냐예요. 다음 강의에서는 코드를 푸시하면 자동으로 테스트하고, 이미지를 만들고, 서버에 배포하는 CI/CD를 배워요.