도커 네트워크 문제 해결.md

[Troubleshooting] Docker 컨테이너에서 apt update 실패 문제 해결

이 문서는 Docker 컨테이너 내에서 인터넷 연결은 되지만 apt update와 같이 도메인 이름을 사용하는 명령어가 실패하는 문제의 원인과 해결 방법을 기록합니다.

1. 문제 상황 (Symptom)

• Docker 컨테이너의 셸(bin/shell)에 접속하여 apt update를 실행하면 저장소 주소를 찾지 못하고 Ign (Ignore) 메시지만 뜨면서 멈추는 현상 발생.
• 하지만 curl 1.1.1.1과 같이 IP 주소로 직접 통신을 시도하면 정상적으로 응답을 받아옴.

문제 발생 시 출력

root@container-id:/\# apt update
Ign:1 [http://ports.ubuntu.com/ubuntu-ports](http://ports.ubuntu.com/ubuntu-ports) noble InRelease
...
0% [Connecting to deb.nodesource.com] [Connecting to ports.ubuntu.com]

# IP 주소로는 통신 가능

root@container-id:/\# curl 1.1.1.1

\<\!DOCTYPE html\>

...

2. 원인 분석 (Cause)

이 문제의 핵심 원인은 컨테이너의 DNS(Domain Name System) 조회 실패입니다.

• curl 1.1.1.1은 IP로 직접 통신하므로 DNS 조회가 필요 없어 성공합니다. 이를 통해 컨테이너의 네트워크 자체는 연결되어 있음을 알 수 있습니다.
• apt update는 ports.ubuntu.com과 같은 도메인 이름을 실제 서버 IP 주소로 변환해야 합니다. 컨테이너가 이 변환 과정을 수행할 DNS 서버를 찾지 못해 연결을 시작하지 못하는 것입니다.
• 이러한 현상은 주로 Docker를 실행하는 호스트(Host) 머신의 DNS 설정이 127.0.0.1과 같은 로컬 주소(localhost)를 가리킬 때 발생합니다. 컨테이너는 기본적으로 호스트의 DNS 설정을 상속받는데, 컨테이너 내부에서 127.0.0.1은 자기 자신을 의미하므로 DNS 서버와 통신할 수 없게 됩니다.

3. 해결 방법 (Solution)

Docker 데몬(daemon)이 모든 컨테이너에 대해 신뢰할 수 있는 공용 DNS 서버를 사용하도록 영구적으로 설정하여 문제를 해결합니다.

1단계: Docker 데몬 설정 파일 열기

호스트 터미널에서 아래 명령어로 Docker 설정 파일을 생성하거나 엽니다.

sudo nano /etc/docker/daemon.json

2단계: 공용 DNS 서버 주소 추가

열린 파일에 아래와 같이 Google DNS(8.8.8.8)와 Cloudflare DNS(1.1.1.1)를 사용하도록 JSON 형식으로 내용을 추가합니다.

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

팁: 만약 파일에 이미 다른 내용이 있다면, {와 } 안에 쉼표(,)를 사용해 "dns": [...] 항목을 추가하세요.

3단계: Docker 데몬 재시작

설정 파일을 저장한 후, 아래 명령어로 Docker 서비스를 재시작하여 변경사항을 적용합니다.

sudo systemctl restart docker

4단계: 컨테이너 재시작

마지막으로, 실행 중인 컨테이너가 새로운 DNS 설정을 적용받을 수 있도록 재시작합니다. overleaf-toolkit의 경우, 해당 디렉토리에서 아래 명령어를 실행합니다.

# overleaf-toolkit 디렉토리에서 실행

bin/stop
bin/up -d

이후 다시 컨테이너 셸에 접속하여 apt update를 실행하면 정상적으로 작동하는 것을 확인할 수 있습니다.

• 이 문서는 Gemini 2.5 Pro를 사용하여 작성되었습니다.