[Docker] host.docker.internal을 사용하는 이유와 활용법

Docker에서 host.docker.internal을 사용하는 이유와 활용법

문제 상황

Docker 컨테이너 내부에서 실행 중인 애플리케이션이 호스트 머신(localhost)에 접근하려고 할 때,
localhost 또는 127.0.0.1을 사용하면 접속 오류가 발생하는 경우가 있다.

예를 들어 아래처럼 nginx 설정을 했을 때,

proxy_pass http://localhost:3000;

502 Bad Gateway 오류가 발생한다면?

원인: 컨테이너 내부의 localhost는 호스트가 아니라 컨테이너 자신을 가리킨다.

---

해결 방법: host.docker.internal 사용

host.docker.internal은 Docker 컨테이너에서 호스트 머신을 가리키는 특수한 주소이다.

예를 들어:

location / {
  proxy_pass http://host.docker.internal:3000;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

이렇게 설정하면, Docker 컨테이너가 호스트의 localhost:3000에 정상적으로 접근할 수 있다.

---

적용 예시

nginx 컨테이너가 React 개발 서버에 프록시할 때

location / {
  proxy_pass http://host.docker.internal:3000;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

---

주의사항

• host.docker.internal은 Windows와 macOS에서는 기본 지원된다.
• Linux에서는 수동 설정이 필요하다.

Linux에서 사용하는 방법

docker-compose.yml에서 extra_hosts를 추가한다:

services:
  nginx:
    image: nginx
    extra_hosts:
      - "host.docker.internal:host-gateway"

또는 docker run 시에 직접 지정할 수 있다:

docker run --add-host=host.docker.internal:host-gateway nginx

---

언제 사용해야 할까?

상황host.docker.internal 필요 여부

nginx가 Docker 밖에 있음	필요 없음 (localhost 사용 가능)
nginx가 Docker 안에 있고, React 앱이 호스트에서 실행 중	필요함 (host.docker.internal 사용)
nginx와 React 앱이 모두 Docker 컨테이너 안	필요 없음 (같은 Docker network 사용)

---

정리

• Docker 컨테이너 안에서 localhost는 컨테이너 자신을 의미한다.
• 호스트 머신의 서비스를 접근하려면 host.docker.internal을 사용해야 한다.
• Linux에서는 host-gateway를 명시적으로 설정해야 한다.
• Docker를 사용할 때는 프록시 경로나 외부 요청 주소를 명확하게 구분해야 한다.