Docusaurus Docker 설치 가이드: Meta의 문서 사이트 생성기 자체 호스팅

작성자:


Docusaurus는 Meta(Facebook)에서 개발한 오픈소스 문서 사이트 생성기입니다. React 기반으로 구축되어 아름다운 기술 문서, API 문서, 블로그를 쉽게 만들 수 있습니다. React, Jest, Prettier 등 수많은 오픈소스 프로젝트의 공식 문서가 Docusaurus로 제작되었습니다. 마크다운으로 작성하고, 버전 관리, 다국어, 검색 기능까지 기본 제공됩니다.

Docusaurus 주요 특징

Docusaurus는 개발자 문서화에 최적화된 기능들을 제공합니다.

핵심 기능

  • 마크다운/MDX: 마크다운에 React 컴포넌트 삽입 가능
  • 버전 관리: 여러 버전의 문서를 동시에 관리
  • 다국어(i18n): 내장 국제화 시스템
  • 검색: Algolia DocSearch 통합 또는 로컬 검색
  • 블로그: 내장 블로그 플러그인
  • 테마 커스터마이징: Swizzle로 컴포넌트 오버라이드

기술적 장점

  • React/TypeScript 기반
  • 빠른 빌드 속도
  • SEO 최적화
  • PWA 지원
  • 플러그인 생태계
  • 다크 모드 기본 지원

사전 요구 사항

  • Docker 및 Docker Compose 설치
  • Node.js 18+ (로컬 개발 시)
  • 500MB 이상 저장 공간

Docker Compose로 Docusaurus 설치

방법 1: 커뮤니티 Docker 이미지 사용

# docker-compose.yml
services:
  docusaurus:
    image: awesometic/docusaurus:latest
    container_name: docusaurus
    restart: unless-stopped
    ports:
      - "3000:80"
    environment:
      - TARGET_UID=1000
      - TARGET_GID=1000
      - AUTO_UPDATE=true
      - WEBSITE_NAME=my-docs
      - TEMPLATE=classic
      - RUN_MODE=development
    volumes:
      - ./docusaurus:/docusaurus

volumes:
  docusaurus-data:

설치 및 실행

# 디렉토리 생성
mkdir docusaurus && cd docusaurus

# docker-compose.yml 생성 (위 내용)

# 컨테이너 실행
docker compose up -d

# 로그 확인 (첫 실행 시 초기화에 1-2분 소요)
docker compose logs -f docusaurus

# 브라우저에서 접속
# http://localhost:3000

방법 2: 커스텀 Dockerfile로 프로젝트 컨테이너화

기존 Docusaurus 프로젝트가 있다면 직접 Docker화할 수 있습니다.

Dockerfile (개발용)

# Dockerfile.dev
FROM node:20-alpine

WORKDIR /app

# 의존성 설치
COPY package*.json ./
RUN npm install

# 소스 복사
COPY . .

# 포트 노출
EXPOSE 3000

# 개발 서버 실행
CMD ["npm", "start", "--", "--host", "0.0.0.0"]

Dockerfile (프로덕션용)

# Dockerfile
# 빌드 스테이지
FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build

# 프로덕션 스테이지
FROM nginx:alpine AS production

COPY --from=builder /app/build /usr/share/nginx/html

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]

Docker Compose (개발 환경)

# docker-compose.dev.yml
services:
  docusaurus:
    build:
      context: .
      dockerfile: Dockerfile.dev
    container_name: docusaurus-dev
    ports:
      - "3000:3000"
    volumes:
      - ./docs:/app/docs
      - ./src:/app/src
      - ./static:/app/static
      - ./docusaurus.config.js:/app/docusaurus.config.js
      - ./sidebars.js:/app/sidebars.js
    environment:
      - NODE_ENV=development

Docker Compose (프로덕션 환경)

# docker-compose.yml
services:
  docusaurus:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: docusaurus
    restart: unless-stopped
    ports:
      - "8080:80"

방법 3: 새 프로젝트 생성 후 Docker화

# 로컬에서 새 프로젝트 생성
npx create-docusaurus@latest my-docs classic --typescript

# 프로젝트 폴더로 이동
cd my-docs

# Dockerfile 및 docker-compose.yml 생성 (위 내용)

# Docker로 실행
docker compose up -d

고급 설정

Caddy 리버스 프록시와 함께 배포

# docker-compose.prod.yml
services:
  docusaurus:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: docusaurus
    restart: unless-stopped
    expose:
      - "80"
    networks:
      - web

  caddy:
    image: caddy:alpine
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    networks:
      - web

volumes:
  caddy_data:
  caddy_config:

networks:
  web:
    driver: bridge

Caddyfile

docs.yourdomain.com {
    reverse_proxy docusaurus:80
}

Traefik 연동

# docker-compose.yml
services:
  docusaurus:
    build: .
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.docs.rule=Host(`docs.yourdomain.com`)"
      - "traefik.http.routers.docs.entrypoints=websecure"
      - "traefik.http.routers.docs.tls.certresolver=letsencrypt"
      - "traefik.http.services.docs.loadbalancer.server.port=80"
    networks:
      - traefik-public

networks:
  traefik-public:
    external: true

주요 설정 파일

docusaurus.config.js

// docusaurus.config.js
module.exports = {
  title: 'My Documentation',
  tagline: '프로젝트 문서 사이트',
  url: 'https://docs.yourdomain.com',
  baseUrl: '/',
  
  // 다국어 설정
  i18n: {
    defaultLocale: 'ko',
    locales: ['ko', 'en'],
  },
  
  // 테마 설정
  themeConfig: {
    navbar: {
      title: 'My Docs',
      items: [
        { type: 'doc', docId: 'intro', label: '문서' },
        { to: '/blog', label: '블로그' },
        { type: 'localeDropdown', position: 'right' },
      ],
    },
    // 다크모드 설정
    colorMode: {
      defaultMode: 'light',
      respectPrefersColorScheme: true,
    },
  },
  
  // 플러그인
  plugins: [
    // 검색 플러그인
    require.resolve('@cmfcmf/docusaurus-search-local'),
  ],
};

sidebars.js

// sidebars.js
module.exports = {
  docs: [
    'intro',
    {
      type: 'category',
      label: '시작하기',
      items: ['getting-started/installation', 'getting-started/configuration'],
    },
    {
      type: 'category',
      label: 'API 문서',
      items: ['api/overview', 'api/authentication'],
    },
  ],
};

관리 명령어

# 컨테이너 로그 확인
docker compose logs -f docusaurus

# 빌드만 실행
docker compose exec docusaurus npm run build

# 사이트 재빌드
docker compose down && docker compose up -d --build

# 프로덕션 빌드 후 서빙
docker compose -f docker-compose.prod.yml up -d

# 캐시 클리어
docker compose exec docusaurus npm run clear

문서 작성 팁

마크다운 문서 구조

docs/
├── intro.md
├── getting-started/
│   ├── installation.md
│   └── configuration.md
├── guides/
│   ├── basic-usage.md
│   └── advanced-features.md
└── api/
    ├── overview.md
    └── endpoints.md

프론트매터 예시

---
id: installation
title: 설치 가이드
sidebar_label: 설치
sidebar_position: 1
tags:
  - 시작하기
  - 설치
---

# 설치 가이드

이 문서에서는 설치 방법을 설명합니다...

MDX로 React 컴포넌트 삽입

---
title: 인터랙티브 문서
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="npm" label="npm">
    ```bash
    npm install my-package
    ```
  </TabItem>
  <TabItem value="yarn" label="yarn">
    ```bash
    yarn add my-package
    ```
  </TabItem>
</Tabs>

버전 관리

# 현재 문서를 v1.0.0으로 태깅
docker compose exec docusaurus npm run docusaurus docs:version 1.0.0

# versioned_docs/version-1.0.0/ 폴더 생성됨
# 이후 docs/ 폴더는 "Next" 버전으로 취급

마무리

Docusaurus는 기술 문서 작성에 최적화된 강력한 도구입니다. React 기반으로 커스터마이징이 자유롭고, 버전 관리와 다국어 지원이 기본 내장되어 있습니다. Docker를 통해 개발 환경을 통일하고, 빌드된 정적 파일을 Nginx나 Caddy로 서빙하면 빠르고 안정적인 문서 사이트를 운영할 수 있습니다.

참고 링크

  • 공식 사이트: https://docusaurus.io
  • GitHub: https://github.com/facebook/docusaurus
  • 커뮤니티 Docker: https://hub.docker.com/r/awesometic/docusaurus
  • 문서: https://docusaurus.io/docs


댓글 남기기