Docker Compose + Nginx를 이용한 정적 웹사이트 구축

Docker와 Nginx를 이용하면 별도의 웹 서버를 직접 설치하지 않고도 HTML, CSS, JavaScript로 작성된 정적(Static) 웹사이트를 손쉽게 운영할 수 있습니다.

이 문서에서는 Docker Compose를 사용하여 Nginx 기반의 정적 웹 서버를 구축하는 과정을 처음부터 차근차근 설명합니다.

1. 프로젝트 생성

먼저 프로젝트 폴더를 생성합니다.

mkdir nginx-static
cd nginx-static

mkdir html
mkdir nginx

최종 디렉터리 구조는 아래와 같습니다.

nginx-static/
├── docker-compose.yml
├── html/
│   ├── index.html
│   └── style.css
└── nginx/
    └── default.conf

각 폴더의 역할은 다음과 같습니다.

폴더설명
html웹사이트의 HTML, CSS, JS, 이미지 등 정적 파일 저장
nginxNginx 설정 파일 저장
docker-compose.ymlDocker Compose 실행 설정

저는 윈도우 기반으로 docker 를 구축하여 활용하기에 위와 같이 제작되었습니다.

2. 웹페이지 작성

index.html

html/index.html

<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <title>Docker + Nginx</title>
    <link rel="stylesheet" href="style.css">
</head>
<body>

    <h1>Hello from Nginx & Docker Compose!</h1>

</body>
</html>

style.css

html/style.css

body{
    background:#fafafa;
    font-family:sans-serif;
    text-align:center;
    padding-top:100px;
}

여기에는 일반적인 HTML, CSS, JavaScript 파일을 자유롭게 추가할 수 있습니다.

예를 들어

html/
├── css/
├── js/
├── images/
├── fonts/
└── index.html

처럼 구성해도 문제없이 동작합니다.

만약 별도의 웹앱으로 제작된 index.html이 있다면 이를 활용한다.

3. Nginx 설정

다음은 Nginx가 어떤 파일을 서비스할 것인지 지정하는 설정입니다.

nginx/default.conf

server {
    listen 80;
    server_name localhost;

    location / {
        root /usr/share/nginx/html;
        index index.html;
    }
}

설정 설명

설정설명
listen 80HTTP 기본 포트(80)에서 서비스
server_name localhost접속할 도메인 이름(예제에서는 localhost)
root웹 파일이 위치한 디렉터리
index기본으로 열릴 페이지

실제로 Docker에서는 HTML 폴더가 다음 위치에 연결됩니다.

/usr/share/nginx/html

따라서 브라우저에서 접속하면

/usr/share/nginx/html/index.html

파일이 자동으로 표시됩니다.

4. Docker Compose 작성

프로젝트 최상위에 docker-compose.yml 파일을 생성합니다.

version: "3.8"

services:
  web:
    image: nginx:stable-alpine
    container_name: nginx-static

    ports:
      - "8080:80"

    volumes:
      - ./html:/usr/share/nginx/html
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf

    restart: unless-stopped

주요 옵션 설명

항목설명
image공식 Nginx Alpine 이미지 사용(가볍고 빠름)
container_name컨테이너 이름 지정
ports호스트의 8080 포트를 컨테이너의 80 포트와 연결
volumesHTML 파일과 Nginx 설정을 컨테이너 내부에 연결
restart재부팅 후 자동 실행

5. 컨테이너 실행

프로젝트 폴더에서 다음 명령을 실행합니다.

docker compose up -d

실행 중인 컨테이너 확인

docker ps

로그 확인

docker compose logs

컨테이너 중지

docker compose down

6. 웹사이트 접속

브라우저에서 아래 주소로 접속합니다.

http://localhost:8080

정상적으로 설정되었다면 다음과 같은 화면이 표시됩니다.

Hello from Nginx & Docker Compose!

아래는 자체적으로 Antigravity 를 활용하여 구축한 html 기반으로 작동되는 간단한 포토edit 웹 앱이 localhost 에서 포트 6789 를 통해 정상적으로 접속한 것을 확인.

7. 파일 수정 후 적용

HTML이나 CSS를 수정한 후에는 별도의 재빌드가 필요하지 않습니다.

예를 들어

<h1>My First Website</h1>

처럼 수정하고 브라우저를 새로고침하면 즉시 변경 사항이 반영됩니다.

단, Nginx 설정 파일(default.conf)을 수정한 경우에는 컨테이너를 재시작해야 합니다.

docker compose restart

8. 프로젝트 전체 구조

nginx-static/
│
├── docker-compose.yml
│
├── html/
│   ├── index.html
│   ├── style.css
│   ├── script.js
│   └── images/
│       └── logo.png
│
└── nginx/
    └── default.conf

폴더 구조를 이해한 상태에서는 index 파일만 유지된다면 몇 번이라도 구조를 바꾸어 사용해도 지속적인 정적 웹 리소스를 체계적으로 관리할 수 있다. 실질적으로 docke-compose.yml 과 nginx 폴더 자체는 최초 설치시에만 필요한 소스이고. 이후 변경사항이 있다면, html 폴더 파일 내에서만 이루어진다.

포트 변경시에만 재설치를 요구한다고 생각하면 편리하다.

마무리

Docker Compose와 Nginx를 이용하면 몇 개의 파일만으로 가볍고 빠른 정적 웹 서버를 구축할 수 있다.

이 방식의 주요 장점은 다음과 같다.

  • 별도의 웹 서버 설치 없이 Docker만으로 운영 가능
  • HTML, CSS, JavaScript 수정 시 즉시 반영
  • Nginx의 높은 성능과 안정성 활용
  • 다른 서버로 프로젝트를 쉽게 이동 가능
  • 향후 HTTPS, 리버스 프록시, 도메인 연결, 캐싱 등 다양한 기능으로 손쉽게 확장 가능

이 기본 구성을 기반으로 개인 홈페이지, 포트폴리오 사이트, 문서 페이지, 랜딩 페이지 등 다양한 정적 웹사이트를 간편하게 운영할 수 있을듯.

관련 게시물