Docker에서 Nginx 웹 서버 실행하기

Nginx를 직접 설치하지 않고도 Docker의 공식 Nginx 이미지를 실행해 웹 서버를 시험할 수 있다. Docker가 설치되어 있고 데몬이 실행 중인 환경에서 아래 명령을 따라 한다. 실습에서는 이미지 다운로드 → 컨테이너 실행 → HTTP 확인 → 파일 교체 → 정리 순서로 살펴본다. 원래 기록에 포함된 2019년 화면도 마지막에 남겨 두었지만, 버전이나 UI가 지금과 다를 수 있다.

1. 이미지와 컨테이너 구분하기

이미지는 Nginx 실행 파일과 기본 설정을 담은 읽기 전용 템플릿이다. docker pull은 이미지를 내려받고, docker run은 그 이미지에서 새 컨테이너를 만든 뒤 실행한다. run에서 로컬에 이미지가 없으면 Docker가 먼저 내려받으므로 pull은 필수 단계가 아니지만, 내려받기 문제와 실행 문제를 분리할 때 편하다.

docker pull nginx:stable
docker image ls nginx

docker image ls에 nginx와 stable 태그가 보이면 이미지가 준비된 것이다. 태그는 특정 버전의 영구 고정값이 아니다. 배포에서 정확히 같은 이미지를 재현해야 하면 검증한 버전 또는 digest를 기록한다. 아래 실습은 계속 nginx:stable을 사용한다.

2. 웹 서버 실행과 응답 확인

다음 명령은 컨테이너 이름을 web-lab으로 정하고 백그라운드(-d)에서 실행한다. -p는 호스트의 127.0.0.1:8080 요청을 컨테이너의 80 포트로 전달한다.

docker run --name web-lab -d -p 127.0.0.1:8080:80 nginx:stable
docker container ps --filter name=web-lab
curl -i http://127.0.0.1:8080/

docker ps의 STATUS가 Up이고 curl이 HTTP 200과 기본 환영 페이지를 출력하면 호스트에서 컨테이너의 Nginx까지 요청이 도달한 것이다. -d의 출력은 컨테이너 ID일 뿐 HTTP 동작 성공을 뜻하지 않는다. 브라우저에서도 http://localhost:8080/을 열어 같은 페이지를 확인할 수 있다.

포트가 어떤 경로로 전달될까

위의 -p 127.0.0.1:8080:80에서 127.0.0.1:8080은 호스트의 바인딩 주소와 포트, 마지막 80은 컨테이너 안에서 Nginx가 듣는 포트다. 컨테이너 이미지에 Nginx가 있어도 호스트의 웹 브라우저가 컨테이너 내부 주소를 직접 찾는 것은 아니다. Docker가 게시 규칙을 만들어 호스트에 들어온 요청을 컨테이너로 전달한다. 주소를 생략한 -p 80:80은 호스트의 모든 인터페이스에 노출될 수 있다. 로컬 실습에서는 루프백 주소와 8080 포트를 쓰면 다른 웹 서버와 충돌할 가능성도 줄어든다.

docker container port web-lab
docker container logs --tail 20 web-lab

flowchart LR
  B[브라우저 localhost:8080] --> H[호스트 127.0.0.1:8080]
  H -->|Docker 게시 규칙| C[컨테이너 80]
  C --> N[Nginx 프로세스]

docker ps의 PORTS 열에서 127.0.0.1:8080->80/tcp처럼 나타나는지도 확인한다. 컨테이너가 즉시 종료됐다면 docker ps -a에서 상태를 보고 docker logs web-lab으로 프로세스 오류를 찾는다. 8080 포트가 이미 사용 중이면 다른 호스트 포트를 선택한다. 외부 PC에서 접속할 목적이라면 바인딩 주소, 방화벽, 클라우드 보안 규칙을 함께 설계해야 한다.

내 HTML 파일 제공하기

컨테이너를 새로 만들어도 정적 파일을 유지하려면 호스트 디렉터리를 읽기 전용으로 마운트할 수 있다. 실습 디렉터리를 만들고 다음 파일을 작성한다.

mkdir -p site
printf '<h1>Hello from Docker</h1>\n' > site/index.html
docker rm -f web-lab
docker run --name web-lab -d \
  -p 127.0.0.1:8080:80 \
  --mount type=bind,source="$(pwd)/site",target=/usr/share/nginx/html,readonly \
  nginx:stable
curl -s http://127.0.0.1:8080/

응답에 Hello from Docker가 보이면 호스트의 site/index.html이 컨테이너의 기본 문서 루트에 연결된 것이다. readonly는 컨테이너가 마운트된 파일을 수정하지 못하도록 한다. 호스트 파일을 고치면 다음 요청에서 바뀐 내용이 보일 수 있다. 이것은 개발용 빠른 반복에 좋지만 배포에서는 테스트를 거쳐 파일을 이미지에 COPY하는 편이 버전 추적과 재현에 유리하다.

현상	가능한 원인과 점검
`bind: address already in use`	호스트 8080을 쓰는 프로세스 또는 다른 컨테이너 확인
기본 Nginx 페이지가 계속 보임	마운트 경로, `site/index.html` 위치, 새 컨테이너 생성 여부 확인
403	호스트 파일·디렉터리 읽기 권한과 컨테이너 실행 사용자 확인
404	URL과 문서 루트의 상대 경로 확인

docker container stats web-lab은 CPU·메모리 같은 사용량을 실시간으로 보여 주지만 HTTP 정상 여부 자체를 보장하지 않는다. docker logout은 레지스트리 인증 정보를 지우는 명령이라 웹 서버 중지와 무관하다. 실습을 마치면 docker rm -f web-lab으로 컨테이너를 정리한다. 바인드 마운트한 site 파일은 호스트에 그대로 남는다.

참고: Docker 포트 게시, 바인드 마운트, Nginx 공식 이미지.