Docker Nginx Compose

이 문서는 Docker Compose 파일에 Nginx 서비스를 선언하고 실행·관리하는 방법을 설명합니다.

docker run은 컨테이너 하나를 명령어로 실행할 때 편리하고, Docker Compose는 Nginx·Node.js·MySQL처럼 여러 컨테이너와 설정을 하나의 파일로 관리할 때 특히 편리합니다.

이 문서는 Docker Nginx 컨테이너에서 구성한 Nginx 컨테이너를 Docker Compose로 실행하고 관리하는 방법을 설명합니다.

1. 이 문서에서 완성할 환경

이 문서를 마치면 다음 작업을 할 수 있습니다.

• nginx-compose.yaml에 Nginx 서비스를 선언하고 Compose 구성을 검증할 수 있습니다.
• Compose 프로젝트의 서비스로 Nginx 컨테이너를 생성하고 실행할 수 있습니다.
• docker compose ps, logs, stop, start와 down으로 서비스와 프로젝트 리소스를 관리할 수 있습니다.
• Linux 서버와 Windows 관리 PC에서 Nginx 웹페이지 접속을 확인할 수 있습니다.
• Compose 프로젝트, 서비스와 컨테이너의 차이를 구분하고 접속 오류를 순서대로 점검할 수 있습니다.

2. 시작하기 전에

다음 항목이 준비되어 있어야 합니다.

• Linux 서버에 Docker Engine과 Docker Compose가 설치되어 있어야 합니다.
• 현재 Linux 사용자가 docker 명령을 실행할 수 있어야 합니다.
• Windows 관리 PC에서 VS Code의 Remote – SSH로 Linux 서버에 연결할 수 있어야 합니다.
• 이전 글에서 만든 ~/projects/nginx-web/html/index.html 파일이 있어야 합니다.
• Linux 서버의 8080번 포트를 다른 프로그램이나 컨테이너가 사용하고 있지 않아야 합니다.
• 예시 IP 주소 192.168.1.231은 실제 Linux 서버의 내부 IP 주소로 바꾸어야 합니다.

3. VS Code에서 nginx-web 작업 폴더 접속

이전 글 Docker Nginx 컨테이너에서 작업했던 nginx-web 폴더에 접속합니다.

VS Code가 최근에 사용한 원격 폴더를 열었다면, 이 문서에서 사용할 nginx-web 작업 폴더를 다시 엽니다.

작업 폴더를 자주 사용한다면 VS Code 환경에서 설명한 것처럼 해당 폴더를 바로 열 수 있도록 Remote – SSH 목록에 등록합니다.

3.1 Remote – SSH에 작업 폴더 등록

작업 폴더를 여는 과정은 Remote – SSH로 서버에 연결하는 과정과 같으며, Open Folder에서 사용할 프로젝트 폴더를 선택한다는 점만 다릅니다.

Activity Bar에서 Remote Explorer를 선택한 뒤, SSH 목록의 project-dev-server connected 오른쪽에 있는 Connect in Current Window 아이콘을 선택합니다.

project-dev-server에 새로 연결되면 Activity Bar에서 Explorer를 선택한 뒤 Open Folder를 선택합니다.

Open Folder에서 /home/apple2ne1/projects/nginx-web/ 폴더를 선택하고 OK 버튼을 누릅니다.

이전 글 Docker Nginx 컨테이너에서 만든 nginx-web 작업 폴더와 그 안의 html 폴더가 Explorer에 표시됩니다.

앞으로 Remote Explorer의 SSH 목록에서 nginx-web 작업 폴더 오른쪽에 있는 Connect in Current Window 아이콘을 선택하면 작업 폴더에 바로 접속할 수 있습니다.

3.2 Remote – SSH에 등록된 작업 폴더 삭제

등록된 작업 폴더 바로가기를 지우려면 해당 항목을 마우스 오른쪽 버튼으로 선택한 뒤 Remove from Recent List를 선택합니다.

3.3 터미널에서 자신의 위치 다시 확인

VS Code에서 새 터미널을 엽니다.

다음 명령을 실행해 자신의 위치를 다시 확인합니다.

pwd

4. 프로젝트 루트 준비

이 문서에서는 이전 글 Docker Nginx 컨테이너에서 준비한 폴더를 계속 사용합니다.

nginx-web/
├── nginx-compose.yaml
└── html/
    └── index.html

nginx-compose.yaml은 이 문서에서 새로 만들고, html/index.html은 이전 글에서 준비한 상태입니다. ./html은 nginx-compose.yaml이 있는 폴더를 기준으로 해석되며, Nginx 컨테이너에 읽기 전용 바인드 마운트로 연결됩니다.

기존 단일 컨테이너 정리

앞 문서에서 docker run으로 생성한 nginx-web 컨테이너가 남아 있으면 Compose 서비스가 같은 8080번 호스트 포트를 게시할 수 없습니다.

먼저 기존 컨테이너를 확인합니다.

docker ps -a --filter name=nginx-web

앞 문서에서 만든 단일 컨테이너가 맞고 더 이상 필요하지 않다면 삭제합니다.

docker rm -f nginx-web

이 명령은 컨테이너를 삭제하지만 바인드 마운트의 원본인 ~/projects/nginx-web/html 폴더와 그 안의 파일은 삭제하지 않습니다. 이 폴더는 컨테이너 밖의 Linux 서버에 저장됩니다.

—

5. Compose 파일 만들기

~/projects/nginx-web/nginx-compose.yaml을 작성합니다.

VS Code의 터미널 패널을 닫고 Explorer에서 nginx-web 작업 폴더를 선택합니다. 왼쪽의 꺾쇠가 아래쪽을 향해 폴더가 펼쳐진 상태인지 확인한 뒤 New File을 선택합니다.

파일명으로 nginx-compose.yaml을 입력합니다.

위 이미지에서 html 폴더의 꺾쇠가 오른쪽을 향하면 폴더가 접힌 상태입니다. nginx-web 폴더의 꺾쇠가 아래쪽을 향하면 폴더가 펼쳐진 상태이며, html과 nginx-compose.yaml이 모두 nginx-web 폴더 안에 있음을 확인할 수 있습니다.

열린 nginx-compose.yaml 파일에 다음 내용을 복사해 작성합니다.

services:
  nginx:
    image: nginx:alpine
    restart: unless-stopped
    ports:
      - "8080:80"
    volumes:
      - ./html:/usr/share/nginx/html:ro

각 항목의 의미는 다음과 같습니다.

Docker Compose가 컨테이너 이름을 자동으로 만들도록 두는 것이 좋습니다.

예를 들어 nginx-compose.yaml이 다음과 같다고 하겠습니다.

services:
  nginx:
    image: nginx:alpine

container_name을 지정하지 않고 실행하면:

docker compose -f nginx-compose.yaml up -d

Compose가 보통 다음 요소를 조합해 컨테이너 이름을 자동으로 만듭니다.

프로젝트명-서비스명-번호

예:

nginx-web-nginx-1

• nginx-web: Compose 프로젝트 이름으로, 일반적으로 Compose 파일이 있는 폴더 이름
• nginx: nginx-compose.yaml에 정의된 서비스명
• 1: 같은 서비스에서 생성된 컨테이너 번호

특정 내부 IP 주소에서만 요청을 받으려면 실제 서버 IP를 지정할 수 있습니다.

ports:
  - "192.168.1.231:8080:80"

Compose 파일 검증

서비스를 실행하기 전에 Compose가 해석한 nginx-compose.yaml의 최종 구성을 확인합니다. 이 파일명은 Docker Compose의 기본 탐색 파일명이 아니므로 모든 Compose 명령에 -f nginx-compose.yaml을 지정합니다.

docker compose -f nginx-compose.yaml config

YAML 들여쓰기, 알 수 없는 속성 또는 잘못된 구성이 있으면 먼저 오류를 수정합니다.

—

6. Nginx 서비스 실행 및 관리

nginx-compose.yaml에 정의된 서비스를 백그라운드에서 실행합니다.

docker compose -f nginx-compose.yaml up -d

• up: nginx-compose.yaml에 정의된 서비스의 컨테이너를 생성하고 실행합니다.
• -d: detached mode의 약자로, 컨테이너를 백그라운드에서 실행합니다.

상태를 확인합니다.

docker compose -f nginx-compose.yaml ps

nginx 서비스의 로그를 확인합니다.

docker compose -f nginx-compose.yaml logs nginx

실시간 로그를 확인하려면 다음 명령을 사용합니다.

docker compose -f nginx-compose.yaml logs -f nginx

Ctrl+C를 누르면 로그 보기만 종료되고 서비스는 계속 실행됩니다.

서비스 중지와 다시 시작

컨테이너를 삭제하지 않고 중지만 하려면 다음 명령을 사용합니다.

docker compose -f nginx-compose.yaml stop

다시 시작합니다.

docker compose -f nginx-compose.yaml start

start는 중지된 기존 컨테이너를 같은 구성으로 다시 시작합니다. Compose 파일을 수정했다면 restart만 실행하지 말고 docker compose -f nginx-compose.yaml up -d로 변경된 구성을 반영해야 합니다.

7. 브라우저에서 접속 확인

먼저 Linux 서버 내부에서 응답을 확인합니다.

curl -I http://localhost:8080

정상 결과에는 다음 상태가 포함됩니다.

HTTP/1.1 200 OK

Windows 관리 PC의 웹 브라우저에서 다음 주소를 엽니다.

http://192.168.1.231:8080

—

8. 브라우저에서 접속되지 않을 때 점검 순서

1단계: 서버 IP 확인

hostname -I

여러 주소가 출력되면 Windows 관리 PC와 같은 내부 네트워크에서 사용하는 서버 IP를 확인합니다.

2단계: Compose 서비스 상태 확인

docker compose -f nginx-compose.yaml ps

nginx 서비스가 실행 중이 아니면 다음 명령으로 다시 생성하고 실행합니다.

docker compose -f nginx-compose.yaml up -d nginx

3단계: Compose 설정 확인

docker compose -f nginx-compose.yaml config

출력된 ports와 volumes가 의도한 값인지 확인합니다.

4단계: Nginx 로그 확인

docker compose -f nginx-compose.yaml logs nginx

이미지 실행 오류, 파일 권한 오류와 Nginx 설정 오류가 있는지 확인합니다.

5단계: 포트 게시 상태 확인

Compose 서비스의 컨테이너 80번 포트가 연결된 호스트 주소를 확인합니다.

docker compose -f nginx-compose.yaml port nginx 80

모든 IPv4 인터페이스에 게시된 출력 예시는 다음과 같습니다.

0.0.0.0:8080

IPv6에도 게시된 환경에서는 [::]:8080이 함께 출력될 수 있습니다.

호스트의 수신 상태도 확인할 수 있습니다.

sudo ss -lntp | grep :8080

6단계: 방화벽과 공개 범위 확인

sudo ufw status

Docker는 게시 포트를 구현하기 위해 자체 방화벽 규칙을 추가하므로 UFW 규칙만으로 Docker 게시 포트의 접근 범위를 통제할 수 없습니다. Compose 파일의 ports에 서버 내부 IP를 지정하면 해당 IP가 연결된 인터페이스로 수신 범위를 제한할 수 있지만, 접근 가능한 클라이언트나 원본 네트워크까지 제한하는 것은 아닙니다. 내부 네트워크 전용 실습에서도 필요한 클라이언트만 접근하도록 Docker와 호스트의 방화벽 정책을 함께 확인해야 합니다.

인터넷에 연결된 운영 서버에서는 Docker가 사용하는 방화벽 백엔드에 맞는 정책을 별도로 설계해야 합니다. iptables 백엔드를 사용한다면 DOCKER-USER 체인에서 Docker 전달 규칙보다 먼저 적용할 사용자 정의 규칙을 구성할 수 있습니다. nftables 백엔드는 체인 구성과 정책 적용 방법이 다르므로 현재 Docker Engine의 방화벽 백엔드와 공식 문서를 먼저 확인합니다.

7단계: Windows에서 포트 연결 확인

Windows PowerShell에서 실행합니다.

Test-NetConnection 192.168.1.231 -Port 8080

정상 결과:

TcpTestSucceeded : True

False라면 다음 항목을 확인합니다.

• 서버 IP가 올바른지
• Nginx 서비스가 실행 중인지
• Compose 파일의 포트 매핑이 올바른지
• Windows 관리 PC와 서버가 같은 네트워크에 있는지
• 공유기의 게스트 네트워크 또는 장치 격리 기능이 활성화되어 있는지
• Docker 및 호스트의 방화벽 정책에서 접근을 허용하는지

—

9. 최종 확인

Linux 서버에서 다음 명령을 차례로 실행합니다.

cd ~/projects/nginx-web
systemctl is-active docker
docker compose -f nginx-compose.yaml config --quiet
docker compose -f nginx-compose.yaml ps
docker compose -f nginx-compose.yaml port nginx 80
curl -I http://localhost:8080

확인할 핵심 결과는 다음과 같습니다.

Docker 서비스: active
Compose 구성: 오류 없음
Nginx 서비스: 실행 중
포트: 호스트 8080번 → 컨테이너 80번
HTTP 응답: 200 OK

Windows 관리 PC의 웹 브라우저에서 http://192.168.1.231:8080을 열어 사용자 웹페이지가 나타나는지 확인합니다.

—

10. 서비스 종료와 프로젝트 리소스 제거

접속과 최종 검증을 마친 뒤 Compose가 만든 컨테이너와 기본 네트워크를 중지하고 제거하려면 다음 명령을 사용합니다.

docker compose -f nginx-compose.yaml down

기본 down 명령으로 다음 항목은 삭제되지 않습니다.

• Docker 이미지
• 명명된 볼륨과 그 안의 데이터
• 익명 볼륨
• 바인드 마운트로 연결한 호스트 폴더의 데이터

호스트의 html 폴더와 파일도 삭제되지 않습니다. 반면 컨테이너의 쓰기 가능 계층에만 저장한 데이터는 컨테이너와 함께 사라질 수 있습니다.

명령의 차이는 다음과 같습니다.

Compose 파일의 최상위 volumes에 선언한 명명된 볼륨과 컨테이너에 연결된 익명 볼륨까지 제거하려면 다음 명령을 사용합니다. 외부 볼륨은 제거되지 않습니다.

docker compose -f nginx-compose.yaml down -v

데이터가 필요한 환경에서는 삭제 대상을 먼저 확인하고 -v 옵션을 사용합니다.

이미지까지 함께 삭제하려면 다음과 같이 실행합니다.

docker compose -f nginx-compose.yaml down --rmi all

—

핵심 명령 모음

cd ~/projects/nginx-web
docker compose -f nginx-compose.yaml config
docker compose -f nginx-compose.yaml up -d
docker compose -f nginx-compose.yaml ps
docker compose -f nginx-compose.yaml logs nginx
curl -I http://localhost:8080
docker compose -f nginx-compose.yaml stop
docker compose -f nginx-compose.yaml start
docker compose -f nginx-compose.yaml down

Docker Engine 설치와 docker 그룹 설정은 Docker Engine 설치에서, 단일 docker run 명령으로 Nginx를 실행하는 방법은 Docker Nginx 컨테이너에서 설명합니다.

—

참고 자료 및 출처

• Docker Compose Quickstart
• Compose 프로젝트 실행, 구성 검사, 상태와 로그 확인 및 종료 명령을 확인했습니다.
• 확인 날짜: 2026-08-09
• How Compose works
• Docker Compose의 기본 파일명 compose.yaml, 서비스, 프로젝트와 상대 경로의 기준을 확인했습니다.
• 확인 날짜: 2026-08-09
• Compose services
• container_name, restart, ports와 volumes 서비스 속성을 확인했습니다.
• 확인 날짜: 2026-08-09
• Packet filtering and firewalls
• Docker 게시 포트와 UFW를 포함한 호스트 방화벽의 관계를 확인했습니다.
• 확인 날짜: 2026-08-09
• nginx Official Image
• Nginx 공식 이미지와 웹 문서 폴더의 바인드 마운트 구성을 확인했습니다.
• 확인 날짜: 2026-08-09

—

관련 문서

• Docker Nginx 컨테이너
• Docker Engine 설치