30초 요약
- 아무것도 설정하지 않은
alpine컨테이너에서date는UTC +0000을 출력한다. - 이미지에
tzdata를 설치하고TZ=Asia/Seoul을 주면KST +0900이 된다. 환경변수는docker run -e, Dockerfile의ENV, compose의environment중 편한 곳에 둔다. - 이미지에
tzdata를 넣고 싶지 않으면 호스트의/usr/share/zoneinfo/Asia/Seoul을/etc/localtime으로 읽기 전용 마운트한다.
증상/목표
컨테이너 로그의 시각이 한국 시간보다 9시간 늦게 찍혀서 로그와 예약 작업을 맞춰 보기 어렵다. 목표는 컨테이너 안의 date와 프로세스가 보는 현재 시각이 KST(UTC+9, +0900)가 되게 하는 것이다.
원인
컨테이너는 이미지에 들어 있는 시간대 설정을 쓴다. 시간대를 정하지 않은 alpine 이미지에서 date "+%Z %z"를 실행하면 UTC +0000이 나온다(아래 확인 절의 실행 결과). 시간대를 바꾸려면 TZ 환경변수를 주거나 /etc/localtime을 바꿔야 한다. 다만 alpine 이미지에는 시간대 정보 패키지 tzdata가 들어 있지 않아, TZ=Asia/Seoul만 주면 오류 없이 그대로 UTC +0000이 나온다(확인 절의 둘째 실행 결과). 그래서 아래 방법 1~3은 tzdata 설치와 함께 쓴다.
해결 방법
1. docker run에 TZ 환경변수 주기
-e TZ=Asia/Seoul로 환경변수를 넘긴다. Alpine에서는 tzdata도 필요하다. 아래는 확인용으로 컨테이너 안에서 설치한 예다.
docker run --rm -e TZ=Asia/Seoul alpine sh -c 'apk add --no-cache tzdata >/dev/null && date "+%Z %z"'2. Dockerfile에 ENV TZ 두기
이미지를 직접 만든다면 설치와 환경변수를 이미지에 넣는 쪽이 가장 단순하다. 실행할 때마다 옵션을 붙일 필요가 없다.
FROM alpineRUN apk add --no-cache tzdataENV TZ=Asia/SeoulCMD ["date", "+%Z %z"]3. docker compose의 environment로 주기
이미지는 건드리지 않고 서비스 단위로 정하려면 compose 파일에 둔다. 이미지에는 tzdata가 이미 있어야 한다. 아래 예는 tzdata만 설치하고 TZ는 정하지 않은 Dockerfile.tzdata로 이미지를 만든다.
FROM alpineRUN apk add --no-cache tzdataCMD ["date", "+%Z %z"]services: app: build: context: . dockerfile: Dockerfile.tzdata environment: TZ: Asia/Seoul4. localtime 파일을 마운트하기
이미지에 tzdata를 설치하지 않으려면 호스트의 zoneinfo 파일을 컨테이너의 /etc/localtime에 읽기 전용으로 붙인다. 호스트에 tzdata가 있어야 한다.
docker run --rm -v /usr/share/zoneinfo/Asia/Seoul:/etc/localtime:ro alpine date "+%Z %z"확인
각 방법 뒤에 date "+%Z %z"가 KST +0900을 출력하는지 판정했다. 수정 전 구간은 시간대를 정하지 않은 컨테이너와, TZ만 주고 tzdata가 없는 컨테이너가 모두 UTC +0000을 내는 것을 재현한다.
검증 범위: Alpine 이미지에서 네 방법을 모두 실행으로 확인했다. 판정한 것은 date 출력뿐이다. Debian·Ubuntu 같은 다른 배포판 이미지, 애플리케이션 런타임(Java·Node 등)과 컨테이너 안 cron의 시간대 동작은 실행하지 않았다.
검증 환경 3항목
| OS | Ubuntu 24.04.5 |
|---|---|
| Docker | 28.0.4 |
| 실행 날짜 | 2026-10-23 |
[XFAIL] alpine 컨테이너의 시간대가 KST인지 확인 — 예상된 실패 재현됨 (/alpine 기본: UTC \+0000/)
> alpine 기본: UTC +0000
[XFAIL] TZ=Asia/Seoul만 주고 tzdata가 없는 alpine이 KST인지 확인 — 예상된 실패 재현됨 (/TZ만, tzdata 없음: UTC \+0000/)
> TZ만, tzdata 없음: UTC +0000[PASS] docker run -e TZ=Asia/Seoul + tzdata 설치 후 KST +0900 [PASS] Dockerfile 이미지를 빌드했다 [PASS] Dockerfile의 ENV TZ=Asia/Seoul 이미지에서 KST +0900 [PASS] compose environment의 TZ로 KST +0900 [PASS] 호스트에 /usr/share/zoneinfo/Asia/Seoul 파일이 있다 [PASS] zoneinfo 파일을 /etc/localtime으로 마운트하면 KST +0900
주의
TZ만 주고tzdata를 넣지 않아도 오류가 나지 않는다. 시각이 그대로UTC +0000이라 설정이 안 먹은 줄 모르고 지나치기 쉬우니,apk add tzdata를 이미지에 넣고date "+%Z %z"로 한 번 확인한다.- 시간대는 표시와 해석에만 영향을 준다. 타임스탬프를 저장하는 DB나 로그 수집기는 UTC로 저장하고 보여 줄 때만 KST로 바꾸는 편이 나중에 서버 위치가 바뀌어도 시각이 어긋나지 않는다.