NestJS와 MkDocs를 함께 사용하여 문서를 관리(Docker)

NestJS와 MkDocs를 함께 사용하여 문서를 관리하고, Docker Compose로 이를 컨테이너화하는 방법을 단계별로 설명하겠습니다.

---

📌 1. 프로젝트 구조

다음과 같은 프로젝트 구조를 가정합니다.

nestjs-mkdocs/
│── backend/        # NestJS 애플리케이션
│   ├── src/
│   ├── package.json
│   ├── Dockerfile
│── docs/           # MkDocs 문서
│   ├── index.md
│   ├── getting-started.md
│   ├── mkdocs.yml
│── docker-compose.yml

---

📌 2. NestJS 애플리케이션 설정

① NestJS 프로젝트 생성

NestJS 애플리케이션을 생성합니다.

nestjs new backend
cd backend

② backend/Dockerfile 작성

NestJS를 컨테이너로 실행하기 위해 backend/Dockerfile을 작성합니다.

# Node.js 베이스 이미지 사용
FROM node:18

# 작업 디렉토리 설정
WORKDIR /app

# 패키지 파일 복사 및 설치
COPY package*.json ./
RUN npm install

# 전체 코드 복사
COPY . .

# 빌드 및 실행
RUN npm run build
CMD ["npm", "run", "start"]

# 포트 설정
EXPOSE 3000

---

📌 3. MkDocs 설정

① MkDocs 설치

루트 디렉토리에 docs/ 폴더를 생성하고, MkDocs 프로젝트를 초기화합니다.

mkdir docs
cd docs
mkdocs new .

② MkDocs 설정 파일 (docs/mkdocs.yml) 작성

docs/mkdocs.yml을 아래와 같이 수정합니다.

site_name: NestJS Documentation
theme:
  name: material
nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - API Docs: api.md

③ 문서 작성 예시

docs/getting-started.md를 작성합니다.

# Getting Started

## Install NestJS
```bash
npm install -g @nestjs/cli
nestjs new my-project

---

## 📌 **4. MkDocs의 `Dockerfile` 작성**
MkDocs를 컨테이너에서 실행하려면 `docs/Dockerfile`을 작성해야 합니다.

```dockerfile
# MkDocs Material 베이스 이미지
FROM squidfunk/mkdocs-material:latest

# 작업 디렉토리 설정
WORKDIR /docs

# 문서 복사
COPY . .

# 문서 실행
CMD ["mkdocs", "serve", "-a", "0.0.0.0:8000"]

---

📌 5. Docker Compose 설정 (docker-compose.yml)

루트 디렉토리에 docker-compose.yml을 생성하고, NestJS와 MkDocs를 함께 실행하도록 설정합니다.

version: '3.8'

services:
  backend:
    build:
      context: ./backend
    ports:
      - "3000:3000"
    volumes:
      - ./backend:/app
    environment:
      - NODE_ENV=production
    depends_on:
      - docs

  docs:
    build:
      context: ./docs
    ports:
      - "8000:8000"
    volumes:
      - ./docs:/docs

---

📌 6. Docker Compose로 실행

아래 명령어를 실행하여 두 개의 컨테이너를 동시에 실행합니다.

docker-compose up --build

이제 브라우저에서 다음 주소로 접속하면 각각의 서비스에 접근할 수 있습니다.

• NestJS API → http://localhost:3000
• MkDocs 문서 → http://localhost:8000

---

📌 7. NestJS API 문서를 자동화하고 MkDocs에 추가 (Swagger)

NestJS의 API 문서를 자동으로 생성하여 MkDocs에 추가할 수도 있습니다.

① Swagger 설치

NestJS에서 Swagger를 설정하려면 @nestjs/swagger 패키지를 설치합니다.

npm install --save @nestjs/swagger swagger-ui-express

② Swagger 설정 (backend/src/main.ts)

src/main.ts 파일을 수정합니다.

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('NestJS API')
    .setDescription('NestJS API 문서')
    .setVersion('1.0')
    .build();
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api-docs', app, document);

  await app.listen(3000);
}
bootstrap();

③ Swagger JSON을 MkDocs로 변환

NestJS API 문서를 Markdown 파일로 변환하여 MkDocs에서 사용하려면 다음과 같이 swagger-to-md 패키지를 활용할 수 있습니다.

1) swagger-to-md 설치

npm install -g swagger-to-md

2) API 문서를 Markdown 파일로 변환

Swagger JSON을 생성하고 이를 MkDocs에 추가합니다.

curl -o docs/api.json http://localhost:3000/api-docs-json
swagger-to-md -i docs/api.json -o docs/api.md

3) docs/mkdocs.yml에 추가

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - API Docs: api.md

이제 http://localhost:8000에서 API 문서를 확인할 수 있습니다.

---

📌 8. 배포 (Docker Hub & GitHub Pages)

① Docker 이미지 빌드 및 푸시

Docker Hub에 업로드하려면 다음 명령어를 실행합니다.

docker build -t myrepo/nestjs-backend ./backend
docker build -t myrepo/mkdocs-docs ./docs
docker push myrepo/nestjs-backend
docker push myrepo/mkdocs-docs

② GitHub Pages에 MkDocs 배포

MkDocs를 GitHub Pages로 배포하려면 다음을 실행합니다.

mkdocs gh-deploy

---

🎯 최종 결과

이제 NestJS와 MkDocs가 Docker Compose를 통해 함께 실행됩니다.

• NestJS API: http://localhost:3000/api-docs
• MkDocs 문서: http://localhost:8000

이 구성을 활용하면 NestJS API 문서를 자동으로 생성하고, MkDocs를 통해 손쉽게 관리할 수 있습니다! 🚀