[docker] Dockerfile 기본 문법과 작성법: 환경을 코드로 기록하기

개발을 하다 보면 흔히 듣는 말이 있습니다.
“내 컴퓨터에서는 잘 되는데, 서버에 올리니까 안 돼요.”
이 문제의 핵심은 개발 환경이 서로 다르다는 데 있습니다.

운영체제 버전, 설치된 라이브러리, 실행 방법이 제각각이면 똑같은 코드라도 결과가 달라집니다.

이 문제를 해결하는 가장 확실한 방법은 환경을 문서화하는 것이고, Docker에서는 그 문서가 바로 Dockerfile입니다.

Dockerfile은 어떤 OS에서 어떤 프로그램을 설치하고, 어떤 코드를 실행할지 단계별로 기록해 두는 환경 레시피라고 할 수 있습니다.

 

1. Dockerfile이 중요한 이유

Dockerfile은 단순히 컨테이너를 만드는 도구를 넘어서, 환경을 코드로 관리한다는 의미가 있습니다.

• 팀원이 프로젝트를 받아서 실행할 때, docker build와 docker run만으로 동일한 환경을 바로 띄울 수 있습니다.
• 서버에 배포할 때도 환경 차이 때문에 발생하는 불필요한 에러를 줄일 수 있습니다.
• 변경 이력이 남기 때문에 “언제 어떤 패키지를 추가했는지” 추적도 가능합니다.

즉, 개발 환경을 사람 머릿속이 아니라 버전 관리되는 코드로 남겨두는 것이죠.

 

 

2. 꼭 알아야 할 네 가지 명령어

Dockerfile에는 다양한 명령어가 있지만, 처음 접하는 사람이라면 다음 네 가지만 알아도 충분합니다.

• FROM: 어떤 이미지를 기반으로 할지 지정합니다. (예: FROM python:3.11-slim)
• RUN: 빌드 과정에서 실행할 명령어를 지정합니다. (예: 패키지 설치)
• COPY: 로컬 파일을 이미지 안으로 복사합니다.
• CMD: 컨테이너가 실행될 때 자동으로 실행되는 명령을 지정합니다.

이 네 가지를 이해하면 대부분의 간단한 서버를 Dockerfile로 감쌀 수 있습니다.

 

 

3. Flask 웹서버 예제

Python Flask로 간단한 웹 서버를 만들어 보겠습니다.

app.py

from flask import Flask
app = Flask(__name__)

@app.route("/")
def hello():
    return "Hello from Docker!"

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

requirements.txt

flask==3.0.0

Dockerfile

# 1. Python 3.11 slim 버전 이미지 사용
FROM python:3.11-slim

# 2. 컨테이너 내 작업 디렉토리 지정
WORKDIR /app

# 3. 의존성 설치
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 4. 소스코드 복사
COPY . .

# 5. Flask 서버 실행
CMD ["python", "app.py"]

# 6. 포트 노출
EXPOSE 5000

 

빌드와 실행

docker build -t flask-demo .
docker run -p 5000:5000 flask-demo

웹브라우저에서 http://localhost:5000에 접속하면 Hello from Docker!라는 문구를 볼 수 있습니다.

 

 

4. 초보자가 자주 겪는 문제와 해결책

1. RUN과 CMD 혼동
   • RUN은 빌드 과정에서, CMD는 컨테이너 실행 시 작동합니다. 서버 실행은 꼭 CMD에 넣어야 합니다.
2. 불필요한 파일 COPY
   • node_modules나 .venv 같은 디렉토리를 그대로 복사하면 충돌이 생깁니다. .dockerignore를 활용하세요.
3. 포트 매핑 실수
   • EXPOSE는 안내 역할만 하고, 실제로는 docker run -p 5000:5000 같은 옵션으로 매핑해야 외부에서 접근 가능합니다.

 

 

5. 실전에서 유용한 팁

• 캐시 활용하기: COPY requirements.txt → RUN pip install → COPY . . 순서로 작성하면, 코드만 수정해도 의존성 설치 단계는 캐싱됩니다.
• 멀티스테이지 빌드: 빌드 도구가 필요한 단계와 실행만 하는 단계를 분리해, 더 가볍고 빠른 이미지를 만들 수 있습니다.
• 환경 변수 사용: ENV 명령어로 실행 환경을 코드에 하드코딩하지 않고 유연하게 관리할 수 있습니다.

 

 

Dockerfile은 단순히 컨테이너를 만들기 위한 기술 문서가 아닙니다.

• 협업에서 환경 차이를 없애는 보증 수표이고,
• 배포에서 재현 가능한 환경을 만드는 핵심입니다.

FROM, RUN, COPY, CMD 같은 기본 명령어부터 익히고, 간단한 Flask 서버 같은 예제를 직접 만들어 보면 금방 감이 잡힙니다. 익숙해지면 멀티스테이지 빌드나 CI/CD와 연계하여, 실무에서도 강력한 무기로 활용할 수 있을 것입니다.