초보자를 위한 Dockerfile Ubuntu 환경 구축 가이드 | 기본·Python까지 완전 안내

1. 소개

Docker와 Dockerfile이란?

Ubuntu를 기반으로 하는 이유

• 풍부한 공식·커뮤니티 문서가 존재하여 학습 비용이 낮다
• 많은 패키지와 도구를 APT로 쉽게 설치할 수 있다
• 경량의 미니멀 이미지(ubuntu:20.04, ubuntu:24.04 등)가 공식적으로 제공된다

본 기사(글)의 목적과 대상 독자

• Dockerfile을 처음 사용해 환경을 구축하고 싶은 분
• Ubuntu에서 개발 환경을 재현성 높게 만들고 싶은 분
• 문제 발생 시 대응 방법까지 포함해 지식을 깊게 배우고 싶은 분

2. Dockerfile의 기본 구성

Dockerfile이란? 그 역할을 이해하자

• 환경 구축 자동화(수작업 재현 불필요)
• 여러 사람이 개발할 때 환경 차이가 없어짐
• CI/CD 파이프라인에도 쉽게 통합 가능

Dockerfile에서 자주 사용되는 기본 명령(디렉티브)

Ubuntu 기반 Dockerfile의 최소 예시

FROM ubuntu:24.04

RUN apt-get update && apt-get install -y 
    curl 
    vim

CMD ["/bin/bash"]

Ubuntu 태그 선택에 대해

• ubuntu:22.04 (LTS: 장기 지원 버전, 안정성 중시)
• ubuntu:24.04 (최신 LTS 후보, 기능 중시)

3. 실전: Ubuntu 기반 Dockerfile 만들기

Ubuntu 환경에 필요한 패키지를 설치하기

• curl: 파일 가져오기 및 API 확인용
• vim: 간단한 텍스트 에디터
• git: 버전 관리 도구
• build-essential: C/C++ 빌드에 필요한 기본 도구 모음

FROM ubuntu:24.04

RUN apt-get update && apt-get install -y 
    curl 
    vim 
    git 
    build-essential

비대화형 설치 설정

ENV DEBIAN_FRONTEND=noninteractive

불필요한 캐시를 삭제하여 경량화하기

RUN apt-get update && apt-get install -y 
    curl 
    vim 
    && rm -rf /var/lib/apt/lists/*

베스트 프랙티스: Dockerfile 정리 방법

• RUN 명령은 가능한 한 합쳐서 레이어 수를 줄인다
• ENV로 명시적으로 버전 및 설정을 정의한다
• 주석을 사용해 처리 목적을 명시한다
• 불필요한 파일을 남기지 않도록 rm이나 --no-install-recommends를 사용한다

RUN apt-get update && apt-get install -y --no-install-recommends 
    curl 
    git 
    && rm -rf /var/lib/apt/lists/*

4. Docker 이미지 빌드와 확인

Dockerfile에서 Docker 이미지를 빌드하기

docker build -t my-ubuntu-image .

• -t 옵션은 이미지에 이름(태그)을 붙이기 위한 것입니다. 예에서는 my-ubuntu-image라는 이름을 붙이고 있습니다。
• .는 Dockerfile이 존재하는 현재 디렉터리를 의미합니다。

빌드한 Docker 이미지 확인

docker images

• REPOSITORY(이미지 이름)
• TAG(태그)
• IMAGE ID(고유 식별자)
• CREATED(생성 일시)
• SIZE(크기)

REPOSITORY        TAG       IMAGE ID       CREATED          SIZE
my-ubuntu-image   latest    abcd1234abcd   5 minutes ago    189MB

Docker 컨테이너를 실행하여 동작 확인

docker run -it my-ubuntu-image

• -it 옵션을 지정하면 인터랙티브 모드로 터미널을 실행할 수 있습니다。
• 정상적으로 시작되면, 컨테이너 내부의 bash 프롬프트가 표시되어 Ubuntu 환경에 로그인한 것과 같은 상태가 됩니다。

curl --version
vim --version

불필요한 이미지와 컨테이너 정리

• 중지된 컨테이너 삭제：

docker container prune

• 사용되지 않는 이미지 삭제：

docker image prune

• 모든 사용되지 않는 데이터(주의！)：

docker system prune

5. 응용: Python 환경 구축

Ubuntu 기반 Dockerfile에서 Python을 사용할 수 있게 하기

apt를 사용하여 Python을 설치하는 방법

FROM ubuntu:24.04

RUN apt-get update && apt-get install -y 
    python3 
    python3-pip 
    && rm -rf /var/lib/apt/lists/*

pyenv로 Python 버전 관리를 수행하기

FROM ubuntu:24.04

ENV DEBIAN_FRONTEND=noninteractive

RUN apt-get update && apt-get install -y 
    git 
    curl 
    make 
    build-essential 
    libssl-dev 
    zlib1g-dev 
    libbz2-dev 
    libreadline-dev 
    libsqlite3-dev 
    wget 
    llvm 
    libncurses5-dev 
    libncursesw5-dev 
    xz-utils 
    tk-dev 
    libffi-dev 
    liblzma-dev 
    && rm -rf /var/lib/apt/lists/*

# pyenv의 설치
RUN git clone https://github.com/pyenv/pyenv.git ~/.pyenv

ENV PYENV_ROOT="$HOME/.pyenv"
ENV PATH="$PYENV_ROOT/bin:$PATH"

RUN echo 'eval "$(pyenv init --path)"' >> ~/.bashrc

# 원하는 Python 버전 설치
RUN pyenv install 3.11.6 && pyenv global 3.11.6

requirements.txt를 사용한 패키지 관리

flask==2.3.2
requests>=2.25.1
pandas

COPY requirements.txt /app/requirements.txt
WORKDIR /app

RUN pip install --no-cache-dir -r requirements.txt

베스트 프랙티스

• Python을 사용할 경우, virtualenv나 venv로 가상 환경을 구축하면 의존 관계 충돌을 방지하기 쉽습니다。
• 캐시 삭제(--no-cache-dir)를 수행하면 Docker 이미지가 경량화됩니다。
• Python 패키지를 설치하기 전에 pip install --upgrade pip으로 최신 버전으로 업데이트하면 오류를 방지할 수 있습니다。

6. 자주 발생하는 문제와 해결 방법

권한 오류

예:

Permission denied

해결 방법:

• 파일을 실행 가능하게 만들기:

  RUN chmod +x script.sh

• 필요에 따라 사용자를 변경하기:

  RUN chown root:root /path/to/file

패키지를 찾을 수 없거나 설치할 수 없음

예:

E: Unable to locate package xxx

해결 방법:

• apt-get update를 반드시 install 앞에 작성한다:

  RUN apt-get update && apt-get install -y curl

• 패키지 이름을 확인하고 오타가 없는지 체크한다

네트워크 관련 오류

예:

Temporary failure resolving 'deb.debian.org'

해결 방법:

• Docker 데몬을 재시작하면 개선될 수 있습니다:

  sudo systemctl restart docker

• Docker의 DNS 설정을 재검토한다 (/etc/docker/daemon.json에 DNS 지정 추가):

  {
    "dns": ["8.8.8.8", "8.8.4.4"]
  }

캐시 영향으로 오래된 상태 그대로의 빌드

해결 방법:

• 캐시를 비활성화하고 다시 빌드한다:

  docker build --no-cache -t my-image .

컨테이너 내에서 시작 명령이 실행되지 않거나 바로 종료되는 경우

원인:

• CMD와 ENTRYPOINT로 지정한 명령이 오류가 발생하고 있다
• CMD에 ["/bin/bash"] 등을 지정해도 인터랙티브하지 않으면 바로 종료한다

해결 방법:

• 컨테이너를 디버그용으로 실행하여 확인한다:

  docker run -it my-image /bin/bash

• CMD와 ENTRYPOINT의 차이를 이해하고 목적에 맞게 사용한다

7. 요약

Ubuntu 기반 Dockerfile 작성 포인트 재확인

• Dockerfile의 기본 구성을 이해하는 것이 첫걸음 FROM, RUN, CMD, ENV 등 명령을 조합하여 환경 구축을 자동화할 수 있습니다.
• Ubuntu는 안정성·유연성이 높은 베이스 이미지 풍부한 패키지, 넓은 사용자층, LTS 버전의 존재로 인해 개발 환경의 기반으로 적합합니다.
• 실용적인 패키지 관리를 통해 필요한 도구와 라이브러리를 설치할 수 apt-get 사용법 및 캐시 삭제, 비대화식 설치 등이 핵심이 됩니다.
• Python과 같은 실용적인 환경 구축도 Dockerfile로 가능 pyenv와 pip, requirements.txt 같은 도구로 재현성이 높은 개발 환경을 구현할 수 있습니다.
• 문제 대응 능력이 안정된 운영에 직결된다 권한, 네트워크, 빌드 캐시 등 흔히 걸리는 포인트를 이해함으로써 개발 효율을 크게 향상시킬 수 있습니다.

Dockerfile 학습의 다음 단계

• Docker Compose를 사용한 다중 컨테이너 구성 관리
• CI/CD 도구(GitHub Actions, GitLab CI 등)와의 연동
• Kubernetes 등 컨테이너 오케스트레이션 도구와의 연동

공식 문서·참고 링크

• Docker 공식 문서(일본어)
• Docker Hub – Ubuntu 공식 이미지
• pyenv GitHub 리포지토리

8. FAQ(자주 묻는 질문)

Q1. Dockerfile에서 Ubuntu 버전을 어떤 것을 선택해야 할까요?

Q2. apt-get install에서 “패키지를 찾을 수 없습니다” 라는 메시지가 나오는 이유는 무엇인가요?

RUN apt-get update && apt-get install -y curl

Q3. Dockerfile에서 환경 변수를 설정하는 방법은?

ENV DEBIAN_FRONTEND=noninteractive

Q4. Dockerfile에서 CMD와 ENTRYPOINT의 차이는 무엇인가요?

CMD ["python3", "app.py"]
# vs
ENTRYPOINT ["python3"]
CMD ["app.py"]

Q5. Dockerfile을 편집했는데 변경 사항이 반영되지 않습니다. 왜인가요?

docker build --no-cache -t my-image .