Docusaurus

Docusaurus Application Stack

The Docusaurus application stack is used to build and deploy documentation portals built with Docusaurus (by Meta) and produce deployment-ready containers for the SCALE environment.

The containers produced in this application stack share common requirements with other application stacks deployed to the SCALE environment. These shared requirements include:

• Security scanning for any vulnerabilities
• Code coverage scanning for test quality
• Staging of the application container in the appropriate Docker container repositories and tagged according to SCALE conventions
• Completion of Unit Testing and User Acceptance Testing
• Gated approvals before allowing deployments into pre-production and production environments
• Audit trail and history of deployment within the SCALE CI/CD Pipeline

Because of the above-listed requirements, the Docusaurus application stack is provided in order to support the build and deployment of documentation portals in a manner that integrates with SCALE requirements and processes. The flow of deployment includes first a Continuous Integration stage of processing in a pipeline prior to deployment in the Continuous Deployment stages. The Continuous Integration stage focuses on building the static documentation site, running scans to check for security vulnerabilities, and staging the container in the appropriate Docker repository ready for deployment. Subsequent pipeline stages deploy the application to the appropriate target Kubernetes spaces.

For details on getting started, see getting started.

For details on repository structure, see repository structure.

The source directory contains the full Docusaurus project. All day-to-day authoring takes place inside source/docs/. The static site is built into source/build/ during CI and served by nginx in the production container.

For details on application configuration, see application configuration.

For details on CI/CD pipelines, see CI/CD pipelines.

For details on upgrading to Pipeline v4.7, see upgrading to Pipeline v4.7.

For details on pipeline definition, see pipeline definition.

Application-Specific Pipeline Configuration

The extends YAML object is a complex object consisting of additional YAML objects. This object is used to extend the pipeline logic (referenced by the repository defined in the resources object) by (a) referencing the correct appstack pipeline entry point (devops/docusaurus.yml for the Docusaurus pipeline) and (b) passing a set of YAML objects as parameters to influence the behavior of the pipeline to meet an application team's specific needs.

The extends YAML object consists of 2 objects beneath it:

• template
• parameters

The template YAML object is a single value set to the initial entry point for the pipeline for the Docusaurus appstack, so it should always be defined as follows:

extends:
  template: devops/docusaurus.yml@spaces

The parameters YAML object is defined immediately following the template object and at the same indentation level. This is the object that requires the most attention and definition to be set up.

The parameters YAML object includes multiple parameters which can be used to configure the CI/CD pipeline. A minimal configuration defining only appVersion looks like the following:

extends:
  template: devops/docusaurus.yml@spaces
  parameters:
    appVersion: 4.8.x

Build Parameters

The build parameter object controls how the Node.js build is performed during CI:

Parameter	Type	Default	Description
build.npmLogin	boolean	false	Set to true to authenticate with the internal Artifactory npm registry. Required when source/.npmrc references the internal registry.

parameters:
  appVersion: 4.8.0
  build:
    npmLogin: true

Node.js Version Configuration

The pipeline builds the Docusaurus site using the Node.js version baked into the Dockerfile (currently Node 22). To override the Node.js version, update the NODE_VERSION build argument in your Dockerfile:

ARG NODE_VERSION=22

The minimum supported Node.js version is 18.

Dockerfile

The Dockerfile uses a multi-stage build:

Stage	Base Image	Purpose
builder	chainguard/wolfi-base	Installs Node.js via apk, runs npm ci
build	builder	Copies source, runs npm run build
test	build	Runs npm run lint and npm run test:ci
runtime	chainguard/wolfi-base	nginx serving the static build output

The test stage executes source/scripts/test-ci.js, which generates the JUnit XML and Cobertura coverage reports consumed by the Azure DevOps pipeline for test result publishing.

If your team requires custom Dockerfile instructions (e.g. additional system packages), add them to the appropriate stage. The builder stage is volume-mounted during local development and is the correct place for build-time dependencies.

Refer to the Docusaurus boilerplate Dockerfile for the canonical version. Update your repository's Dockerfile to match when upgrading pipeline versions.

For details on defining hostspaces, see defining hostspaces.

For details on skipping deployments, see skipping deployments.

nginx Configuration

The config/nginx.conf file controls how the production container serves the static site. After upgrading the pipeline version, compare your nginx.conf against the boilerplate version to pick up any new security headers, compression settings, or routing rules.

Local Development

All commands run inside Docker — no host-side npm, node, or yarn required.

Build the Development Image

Build once (or whenever source/package.json or source/package-lock.json changes):

docker build --target builder -t docusaurus:local-dev .

Day-to-Day Authoring (hot-reload, no search)

Starts a live-reloading dev server at http://localhost:3000/docs/. Your local source/ directory is bind-mounted so changes to docs, config, and static assets are reflected immediately:

docker run --rm -e DOCUSAURUS_SEARCH=false \
  -v "${PWD}/source:/app" -v /app/node_modules -p 3000:3000 \
  docusaurus:local-dev npm run dev

Note: Search does not work in dev mode. Use the production preview below to test search before opening a PR.

Preview Production Output Locally (search enabled)

# Build the static site into source/build/
docker run --rm \
  -v "${PWD}/source:/app" -v /app/node_modules \
  docusaurus:local-dev npm run build

# Serve the built output
docker run --rm \
  -v "${PWD}/source:/app" -v /app/node_modules -p 3000:3000 \
  docusaurus:local-dev npm run serve

Navigate to http://localhost:3000/docs/.

Full Production Image

Mirrors exactly what the CI pipeline produces and what nginx serves in the cluster:

docker build -t docusaurus:prod .
docker run --rm -p 3000:3000 docusaurus:prod

For details on Horizontal Pod Autoscaler, see Horizontal Pod Autoscaler.

For details on Pod Anti-Affinity, see Pod Anti-Affinity.

For details on detailed pipeline configuration, see detailed pipeline configuration.

For details on Kubernetes deployment objects, see Kubernetes deployment objects.

For details on troubleshooting, see troubleshooting.