A Record of Introducing Docker Compose to a Docusaurus Project
This article documents the steps for introducing Docker Compose
to a Docusaurus project for local development.
To unify the local development environment and simplify setup, Docker Compose was introduced to a Docusaurus (v3.8.0
) project. Before this, the setup involved directly installing Node.js (v22.16.0
) and pnpm (v10.11.0
) on each developer's local machine.
Sources
1. Creating the Development Dockerfile (Dockerfile.dev
)
To define a Docker image specifically for local development, Dockerfile.dev
was created with the following steps:
-
File Creation A file named
Dockerfile.dev
was created in the project root. -
Specify Base Image To maintain consistency with the production
Dockerfile
,node:22.16.0-alpine
was specified as the base image. -
Enable pnpm and Install Dependencies After running
corepack enable pnpm
,package.json
andpnpm-lock.yaml
are copied into the container, and all packages, including development dependencies, are installed usingpnpm install --frozen-lockfile
. -
Expose Port and Set Startup Command The default Docusaurus development port
3000
is exposed, and the startup command is set topnpm start --host 0.0.0.0 --no-open
. This allows access from outside the container while suppressing the unnecessary automatic opening of a browser.
# 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. Creating the Docker Compose Configuration File (docker-compose.yml
)
To define and manage the development service, docker-compose.yml
was created with the following steps:
-
File Creation A file named
docker-compose.yml
was created in the project root. -
Service Definition A development service named
app
was defined, with the container name set tohkdocs_dev_app
. The build context was set to the project root (.
), and the Dockerfile to be used was specified asDockerfile.dev
. -
Port Mapping Configuration The host's port
3000
is mapped to the container's port3000
. -
Volume Mount Configuration For source code synchronization,
.:/app:cached
was set. To isolate thenode_modules
and.docusaurus
directories,/app/node_modules
and/app/.docusaurus
were configured as container-specific volumes. -
Environment Variables and Other Settings
NODE_ENV=development
was set.CHOKIDAR_USEPOLLING=true
is prepared but commented out for cases of unstable hot reloading. For interactive execution,tty: true
andstdin_open: true
were set.
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. Updating the Docker Build Context Exclusion File (.dockerignore
)
To optimize the Docker image build efficiency and size, the .dockerignore
file was updated. The main exclusions include .git
, node_modules
, build
, .docusaurus
, Docker-related files themselves, deployment scripts, environment-specific files, log files, OS-specific files, and IDE configuration files.
Since pnpm-lock.yaml
is used by the COPY
command inside Dockerfile.dev
, it is not included in the .dockerignore
file.
# 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. Using and Verifying the Development Environment
-
Starting the Development Environment From the terminal in the project root directory, start the development environment using
docker-compose up --build
for the first time or after changing configuration files. For subsequent starts, usedocker-compose up
. -
Verifying in the Browser Access
http://localhost:3000
in a browser and confirm that the Docusaurus site is displayed. -
Testing Hot Reload Edit and save a source code file in your editor on the host machine and confirm that the changes are immediately reflected in the browser (hot reload).
If Hot Reload is UnstableYou can address this by uncommenting
CHOKIDAR_USEPOLLING=true
indocker-compose.yml
, or by adding the--poll
option to theCMD
inDockerfile.dev
and restarting withdocker-compose up --build
. -
Stopping the Development Environment Stop the containers by pressing
Ctrl + C
in the terminal where the development server is running. To completely remove the containers and associated resources (like networks), run thedocker-compose down
command.