Local Development Setup
Relevant source files
The following files were used as context for generating this wiki page:
The local development setup for this project is centered around using Docker and Docker Compose to create a consistent, containerized environment. This approach allows developers to build, preview, and test the documentation site and application guides without needing to install dependencies directly on their host machine. The core of this setup is the docker compose watch command, which provides live-reloading capabilities for a fast feedback loop during development.
This setup requires Docker Desktop version 4.24 or later, or Docker Engine with Docker Compose version 2.22 or later. The primary tools are a compose.yaml file to define the services and a Dockerfile (often a development-specific Dockerfile.dev) to define the container environment.
Sources: CONTRIBUTING.md:29-32, content/guides/nodejs/develop.md
Core Workflow
The standard workflow for local development involves cloning the repository, checking out a new branch, and starting the development server using Docker Compose. Changes made to the source files are automatically reflected in the running container.
Sources: CONTRIBUTING.md:34-55
Development Steps
- Fork and Clone: Fork the
docker/docsrepository and clone it to your local machine. - Configure Upstream: Add the original repository as an upstream remote to keep your fork synced.
- Create a Branch: Check out a new branch for your changes.
- Start Development Server: Run
docker compose watchto build and start the services. - Preview: Access the site at
http://localhost:1313to see your changes live. - Stop Server: Press
<Ctrl+C>and then rundocker compose downto stop the services.
Sources: CONTRIBUTING.md:36-62
The following diagram illustrates the local development startup process.
Sources: CONTRIBUTING.md:53-57
Compose Watch for Live Reloading
A key feature of the development setup is the use of docker compose watch to automatically update running services when source code changes. This is configured in the compose.yaml file under the develop.watch section for a given service.
This eliminates the manual rebuild-and-restart cycle, providing a seamless development experience.
Sources: content/guides/reactjs/develop.md:24-27, content/guides/nodejs/develop.md:112-115
Configuration
The watch key accepts a list of rules, each specifying a path to watch and an action to take when a change is detected.
services:
react-dev:
build:
context: .
dockerfile: Dockerfile.dev
ports:
- "5173:5173"
develop:
watch:
- action: sync
path: .
target: /app
Sources: content/guides/reactjs/develop.md:46-58
Watch Actions
Different actions can be triggered based on the files changed.
| Action | Description | Example Use Case |
|---|---|---|
sync | Synchronizes file changes from the host into the container at the specified target path. | Updating source code files like .js, .html, .css. |
rebuild | Rebuilds the service's Docker image and restarts the container. | Changing the Dockerfile. |
restart | Restarts the service's container without rebuilding the image. | Changing configuration files like package.json. |
Sources: content/guides/vuejs/develop.md:76-88, content/guides/ruby/develop.md:83-86
This sequence diagram shows how a file change on the host machine triggers a sync action in the running container.
Development vs. Production Services
The compose.yaml files in the guides often define separate services for development and production environments. This allows each environment to be optimized for its specific purpose.
- Development Service (
*-dev): Uses a development-specific Dockerfile (Dockerfile.dev), enables live-reloading, and may expose debugging ports. - Production Service (
*-prod): Uses a multi-stage build to create a minimal, optimized production image, often served by a web server like Nginx.
Sources: content/guides/reactjs/develop.md:42-45, content/guides/angular/develop.md:59-62, content/guides/nodejs/containerize.md:100-128
The diagram below shows a typical multi-service architecture for a React application.
Development Dockerfile (Dockerfile.dev)
To support the development environment, a separate Dockerfile.dev is often used. Its purpose is to set up a container with all necessary development dependencies and tools, such as a Node.js environment with a live-reloading development server.
This contrasts with the production Dockerfile, which typically uses a multi-stage build to create a small, secure, and efficient final image.
Sources: content/guides/angular/develop.md:29-31, content/guides/vuejs/develop.md:32-34
Example Dockerfile.dev for an Angular App
# Stage 1: Development - Angular Application
ARG NODE_VERSION=24.7.0-alpine
# Set the base image for development
FROM node:${NODE_VERSION} AS dev
# Set environment variable to indicate development mode
ENV NODE_ENV=development
# Set the working directory inside the container
WORKDIR /app
# Copy only the dependency files first to optimize Docker caching
COPY package.json package-lock.json ./
# Install dependencies using npm with caching
RUN --mount=type=cache,target=/root/.npm npm install
# Copy all application source files into the container
COPY . .
# Expose the port Angular uses for the dev server
EXPOSE 4200
# Start the Angular dev server and bind it to all network interfaces
CMD ["npm", "start", "--", "--host=0.0.0.0"]
Sources: content/guides/angular/develop.md:33-57
Local Testing
Before submitting changes, it's recommended to run local validation tests. These tests check for issues like broken links and incorrectly formatted markup.
The tests can be executed with a single command:
$ docker buildx bake validate
If this command completes without errors, the changes are ready for a pull request.
Sources: CONTRIBUTING.md:68-75