Docker에서 시간대(TZ)를 Asia/Seoul로 변경하는 방

🌐 Docker에서 시간대(TZ)를 Asia/Seoul로 변경하는 방법

🕒 왜 시간대 설정이 중요할까?

Docker 컨테이너는 기본적으로 UTC 시간대를 사용합니다. 하지만 로그 분석, 스케줄러 실행, 웹 서버 응답 시간 등에서는 시스템 시간대와 일치해야 할 때가 많습니다. 특히 한국에서는 Asia/Seoul로 설정해야 로그와 시스템 동작이 맞게 정렬됩니다.

📌 방법 1: 컨테이너 실행 시 환경변수로 설정하기

가장 간단한 방법은 -e TZ=Asia/Seoul 옵션을 사용하는 것입니다.

# 예시: Ubuntu 기반 이미지
docker run -d \
  -e TZ=Asia/Seoul \
  -v /etc/localtime:/etc/localtime:ro \
  --name my-container \
  your-image-name

옵션 설명:

• -e TZ=Asia/Seoul → 환경변수로 시간대 설정
• -v /etc/localtime:/etc/localtime:ro → 호스트의 시간 설정을 컨테이너에 반영

📌 방법 2: Dockerfile에 시간대 설정 추가하기

컨테이너를 매번 설정하지 않고 이미지 생성 시 고정 시간대를 설정할 수 있습니다.

Ubuntu 기반 Dockerfile 예시

FROM ubuntu:22.04

ENV TZ=Asia/Seoul

RUN apt-get update && apt-get install -y tzdata \
    && ln -fs /usr/share/zoneinfo/Asia/Seoul /etc/localtime \
    && dpkg-reconfigure -f noninteractive tzdata

Alpine 기반 Dockerfile 예시

FROM alpine

ENV TZ=Asia/Seoul

RUN apk add --no-cache tzdata \
    && cp /usr/share/zoneinfo/Asia/Seoul /etc/localtime \
    && echo "Asia/Seoul" > /etc/timezone

✅ 적용 확인 방법

docker exec -it my-container date

위 명령어로 컨테이너 내부의 시간대를 확인할 수 있습니다. KST가 표시되면 성공입니다.

📎 마무리 정리

• 일회성: -e TZ 옵션 + /etc/localtime 마운트
• 영구 반영: Dockerfile에서 tzdata 패키지로 설정
• 적용 확인: date 명령으로 확인

Docker는 가볍고 편리하지만, 기본 설정이 UTC이기 때문에 운영 환경에 맞춰 시간대를 꼭 맞춰야 합니다. 이 글을 참고해서 Flask, Django, Node.js 등 다양한 프로젝트에 알맞게 적용해보세요.