メインコンテンツまでスキップ

DocusaurusプロジェクトへDocker Composeを導入した記録

この記事では、Docusaurusのローカル環境開発時のために、Docker Composeを導入した際の手順を整理します。

導入の背景

ローカル開発環境の統一とセットアップの簡略化を目的とし、Docusaurus (v3.8.0) プロジェクトにDocker Composeを導入しました。導入前は、Node.js (v22.16.0) およびpnpm (v10.11.0) を開発者のローカルマシンに直接インストールして運用していました。

Sources​

1. 開発用Dockerfileの作成 (Dockerfile.dev)​

ローカル開発専用のDockerイメージを定義するため、以下の手順でDockerfile.devを作成しました。

  1. ファイル作成 プロジェクトルートにDockerfile.devという名前でファイルを作成。

  2. ベースイメージ指定 本番用Dockerfileとの整合性を考慮し、node:22.16.0-alpineをベースイメージとして指定。

  3. pnpm有効化と依存関係インストール corepack enable pnpmを実行後、package.jsonとpnpm-lock.yamlをコンテナにコピーし、pnpm install --frozen-lockfileで開発依存を含む全パッケージをインストール。

  4. ポート開放と起動コマンド設定 Docusaurusのデフォルト開発ポート3000を開放し、起動コマンドとしてpnpm start --host 0.0.0.0 --no-openを設定。これにより、コンテナ外部からのアクセスを許可しつつ、不要なブラウザの自動起動を抑制。

Dockerfile.dev
# syntax=docker/dockerfile:1
FROM node:22.16.0-alpine AS development

WORKDIR /app

RUN corepack enable pnpm

COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

EXPOSE 3000
CMD ["pnpm", "start", "--host", "0.0.0.0", "--no-open"]

2. Docker Compose設定ファイルの作成 (docker-compose.yml)​

開発用サービスの定義と管理のため、以下の手順でdocker-compose.ymlを作成しました。

  1. ファイル作成 プロジェクトルートにdocker-compose.ymlという名前でファイルを作成。

  2. サービス定義 appという名称で開発用サービスを定義し、コンテナ名をhkdocs_dev_appとした。ビルドコンテキストをプロジェクトルート (.)、使用するDockerfileをDockerfile.devに指定。

  3. ポートマッピング設定 ホストのポート3000をコンテナのポート3000にマッピング。

  4. ボリュームマウント設定 ソースコード同期のため.:/app:cachedを、node_modulesと.docusaurusディレクトリの隔離のためそれぞれ/app/node_modulesと/app/.docusaurusをコンテナ専用ボリュームとして設定。

  5. 環境変数とその他設定 NODE_ENV=developmentを設定。ホットリロード不安定時のためのCHOKIDAR_USEPOLLING=trueはコメントアウト状態で準備。対話的実行のためtty: trueとstdin_open: trueを設定。

docker-compose.yml
version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile.dev
    container_name: hkdocs_dev_app
    ports:
      - "3000:3000"
    volumes:
      - .:/app:cached
      - /app/node_modules
      - /app/.docusaurus
    environment:
      - NODE_ENV=development
      # CHOKIDAR_USEPOLLING=true
    tty: true
    stdin_open: true

3. Dockerビルドコンテキスト除外設定 (.dockerignore) の更新​

Dockerイメージのビルド効率とイメージサイズを最適化するため、.dockerignoreファイルを更新しました。主な除外対象は、.git、node_modules、build、.docusaurus、Docker関連ファイル自体、デプロイ用スクリプト、環境依存ファイル、ログファイル、OS固有ファイル、IDE設定ファイルなどです。

注意

pnpm-lock.yamlはDockerfile.dev内でCOPYコマンドにより使用するため、.dockerignoreの除外対象には含めません。

.dockerignore
# Git
.git
.gitignore

# Node.js
node_modules

# Docusaurus build output and cache
build
.docusaurus

# Docker related files
Dockerfile
Dockerfile.dev
docker-compose.yml
docker-compose.*.yml

# Deployment scripts & environment specific files
deploy.sh
.env
*.local

# Logs
*.log
pnpm-debug.log*

# IDE/Editor specific
.DS_Store
.vscode/
.idea/

4. 開発環境の利用と動作確認​

  1. 開発環境の起動 プロジェクトルートディレクトリのターミナルから、初回または構成ファイル変更時はdocker-compose up --build、2回目以降はdocker-compose upコマンドで開発環境を起動。

  2. ブラウザでの表示確認 ブラウザでhttp://localhost:3000にアクセスし、Docusaurusサイトが表示されることを確認。

  3. ホットリロードのテスト ホストマシン上のエディタでソースコードを編集・保存し、変更が即座にブラウザに反映される（ホットリロード）ことを確認。

    ホットリロードが不安定な場合

    docker-compose.ymlのCHOKIDAR_USEPOLLING=trueのコメントアウトを解除、またはDockerfile.devのCMDに--pollオプションを追加し、docker-compose up --buildで再起動することで対応可能です。

  4. 開発環境の停止 開発サーバーを起動したターミナルでCtrl + Cを押すことでコンテナを停止。コンテナと関連リソース（ネットワークなど）を完全に削除する場合は、docker-compose downコマンドを実行。