Local Development Setup

Relevant source files

The following files were used as context for generating this wiki page:

• docker-compose-docs.yml
• README.md
• package.json
• CLAUDE.md
• CONTRIBUTING.md
• content/en/administrators_guide/getting_started.md
• content/en/administrators_guide/build.md

This document outlines the process for setting up a local development environment for the Datadog documentation project. The project uses the Hugo static site generator, with a build system composed of Node.js, Python, and Makefiles to manage dependencies, process content, and run a local development server. A containerized setup using Docker is also available for a consistent environment.

The primary goal of this setup is to enable contributors to build the site, preview changes locally, and run tests before submitting pull requests. The local server typically runs on port 1313.

Sources: CLAUDE.md:5-7, 50-51, README.md:3-5

Prerequisites

Before setting up the local environment, ensure the following tools are installed on your system:

Tool	Required Version	Notes
Node.js	>= 20.11.0	Used for build automation and assets.
Yarn	v3.6.1	The specified package manager.
Python	3	For content processing scripts.
Docker	Latest	Optional, for containerized builds.

Sources: CLAUDE.md:48-51, README.md:34

System Architecture

The local development environment is orchestrated by a Makefile that coordinates several key technologies. Hugo is the core static site generator, while Node.js and Python scripts handle build automation, asset processing, and fetching external content like integration data and API examples.

Sources: CLAUDE.md:27-40

The following diagram illustrates the high-level architecture of the build system.

Setup and Installation

The setup process involves cloning the repository, installing all necessary dependencies using a single command, and then starting the development server.

This flowchart shows the recommended setup path.

1. Install Dependencies

After cloning the repository, run the make dependencies command. This single command installs all required dependencies, including:

• Node.js packages via yarn install.
• Python virtual environment and packages via make hugpython.
• External content repositories required for the build.

Alternatively, yarn install can be run to install only the Node.js dependencies.

Sources: CLAUDE.md:22-24

2. Run the Development Server

Several commands are available to start the local development server, which runs on http://localhost:1313. The choice of command depends on the development needs.

Command	Description	Source File
yarn start or make start	Performs a full build, including external dependencies, and runs the dev server.	CLAUDE.md:10
yarn run start	Runs the basic Hugo development server without pre-build steps.	CLAUDE.md:11
make start-no-pre-build	Skips fetching external dependencies, then builds and runs the server.	CLAUDE.md:12
make start-docker	Builds and runs the entire development environment inside a Docker container.	CLAUDE.md:14

Sources: CLAUDE.md:9-14, package.json:7

Development Workflow

Contributing to the documentation requires adhering to a specific branching and pull request workflow to ensure CI/CD pipelines run correctly and generate branch previews.

Branching Convention

All branches MUST be named using the format <name>/<description>. The forward slash (/) is critical.

Failure to follow this convention results in:

• The GitLab pipeline not running.
• No branch preview being generated.
• The pull request failing CI checks.

*Sources: README.md:28-30, CLAUDE.md:43-47 *

Contribution Process

The following sequence diagram illustrates the typical contribution lifecycle, from creating a branch to merging a pull request.

Docker-Based Development

For a fully containerized and reproducible development environment, the project provides a docker-compose-docs.yml file. The make start-docker command utilizes this configuration.

Docker Compose Configuration

The docker-compose-docs.yml file defines a single service named docs.

• Image: It uses a pre-built hugo-builder image.
• Command: The container executes make start-in-docker upon startup.
• Ports: It maps port 1313 on the host to port 1313 in the container, allowing access to the Hugo server.
• Volumes: The current project directory (.) is mounted into the /src directory inside the container, ensuring that any local file changes are immediately reflected.

Sources: docker-compose-docs.yml:1-12

Here is a snippet from the configuration file:

# docker-compose-docs.yml
services:
  docs:
    # This image is built by our CI and contains all the dependencies
    # needed to run the documentation site.
    image: hugo-builder
    command: make start-in-docker
    ports:
      - "1313:1313"
    volumes:
      - .:/src

Sources: docker-compose-docs.yml:2-11

Build and Test Commands

The project includes scripts and Makefile targets for building, testing, and cleaning the environment.

Command	Description	Source File
yarn build	Creates a production build of the site.	package.json:8
make build	Orchestrates the full production build process.	CLAUDE.md:17
yarn run build:hugo	Runs only the Hugo build step.	CLAUDE.md:18
yarn run jest-test	Executes JavaScript tests using Jest.	CLAUDE.md:21
make clean	Removes generated files from the build process.	CLAUDE.md:22
make clean-all	Performs a deep clean, removing the environment, repos, and all generated files.	CLAUDE.md:23

Sources: CLAUDE.md:16-23, package.json:8-12