Introduce devcontainer service container based development environment (#705)

.devcontainer/devcontainer.json

@@ -0,0 +1,23 @@
+{
+  "name": "React UI (${localWorkspaceFolderBasename})",
+  "initializeCommand": "bash ./setup.sh",
+  "dockerComposeFile": [
+    "../docker-compose.yml"
+  ],
+  "service": "devcontainer",
+  "shutdownAction": "stopCompose",
+  "workspaceFolder": "/workspace",
+  "forwardPorts": [
+    "docs:8000"
+  ],
+  "portsAttributes": {
+    "docs:8000": {
+      "label": "Docs server",
+      "protocol": "http",
+      "onAutoForward": "openBrowser"
+    }
+  },
+  "otherPortsAttributes": {
+    "onAutoForward": "ignore"
+  }
+}

.env.dist

@@ -1,13 +1,51 @@
-###############################
-# Docker compose configuration #
-###############################
+################################
+# Docker Compose configuration #
+################################
 
-# Host system port where the live documentation is to be made accessible
-COMPOSE_START_PORT=8000
+# Must match Docker Compose project name used to start the other service containers to allow devcontainer
+# to communicate with them (setup.sh derives this from the directory basename by default)
+COMPOSE_PROJECT_NAME=react-ui
 
-# Host system port where Playwright Component Testing report is to be made accessible
+# Docker compose ports for Docs server instances
+COMPOSE_DOCS_SERVER_PORT=8000
+
+# Docker compose ports for Playwright Component Testing report server
 COMPOSE_PLAYWRIGHT_REPORT_PORT=9323
 
+# Flag whether the `node` and `docs` service containers should automatically install dependencies,
+# build, and run the application (JavaScript files watcher, docs server) when they start
+COMPOSE_AUTOSTART=false
+
 # Ownership of the files created in the container
+# ⚠️ [Linux] This needs to be set to the output of `id --user`
+# ⚠️ [MacOS] This needs to be set to 1000
 COMPOSE_UID=1000
+# ⚠️ [Linux] This needs to be set to the output of `id --group`
+# ⚠️ [MacOS] This needs to be set to 1000
 COMPOSE_GID=1000
+
+#############################
+# Devcontainer configuration #
+#############################
+
+# IDEs automatically mount the host's SSH agent socket into the container
+# Visual Studio Code does this by default, it can be disabled by setting the following variable to true.
+# JetBrains IDEs do not mount this by default, but they can be configured to do so.
+BLOCK_SSH_AUTH_SOCK=false
+
+# Select your preferred editor and visual (vim, nano)
+EDITOR=vim
+VISUAL=vim
+
+# Select your preferred shell (/bin/bash, /bin/fish, /bin/zsh)
+SHELL=/bin/bash
+
+###########################
+# Playwright configuration #
+###########################
+
+# Number of workers to use to run Playwright tests
+PW_WORKERS=1
+
+# Port used by Playwright Component Testing to serve the test files
+PW_CT_PORT=3100

.gitignore

@@ -1,11 +1,13 @@
 /coverage
+/docker-compose.yml
+/docker/react_ui_devcontainer_local
+!/docker/react_ui_devcontainer_local/Dockerfile.dist
 /dist
 /node_modules
 /playwright-report/
 /site
 /src/docs/_assets/generated/*
 /tests/playwright/.temp/
 .env
-.env.playwright
 statistics.html
 !.gitkeep

CLAUDE.md

@@ -4,17 +4,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Commands
 
-All `npm` commands must be run inside Docker containers. Use `node_shell` for most tasks, `playwright` for visual tests.
+All commands below are meant to be run directly inside the Docker container `devcontainer`.
+If you open the project in a Dev Container, you can run these commands without manually
+starting Docker Compose on the host.
 
-```bash
-# Enter node_shell container
-docker compose run --rm node_shell
-
-# Enter playwright container (for visual tests)
-docker compose run --rm --service-ports playwright
-```
-
-**Within `node_shell`:**
 
 ```bash
 npm run lint                          # All linters (ESLint + Stylelint + Markdownlint)
@@ -23,11 +16,6 @@ npm run stylelint                     # SCSS linting
 npm run test:jest                     # All Jest unit tests
 npm run test:jest:ts -- <file>        # Single TypeScript test file
 npm run test:jest:js -- <file>        # Single JavaScript test file
-```
-
-**Within `playwright`:**
-
-```bash
 npm run test:playwright-ct:all                          # All component tests
 npm run test:playwright-ct:all-with-update              # Update snapshots
 npm run test:playwright-ct:all -- -- src/components/Button   # Tests for one component

docker-compose.base.yml

@@ -0,0 +1,95 @@
+services:
+  # This service is responsible for providing the main development environment for developers
+  devcontainer:
+    hostname: ${COMPOSE_PROJECT_NAME:-react-ui}_devcontainer
+    build:
+      context: docker/react_ui_devcontainer/
+      dockerfile: Dockerfile
+    # Start dependent services before starting the `devcontainer` service to ensure that the necessary environments
+    # and tools are available when the `devcontainer` starts.
+    depends_on:
+      node:
+        condition: service_started
+      playwright:
+        condition: service_started
+      docs:
+        condition: service_started
+    # Run as host UID/GID so files created in mounted volumes are owned correctly on the host.
+    # The images use `fixuid` (https://github.com/boxboat/fixuid) to remap the built-in `developer`
+    # user to these IDs at startup — the `user:` directive is required for that remap to work.
+    # Applied to all services below for the same reason.
+    user: ${COMPOSE_UID}:${COMPOSE_GID}
+    # Keep the container running indefinitely to allow developers to attach to it and use it as their development environment
+    command: sleep infinity
+    # Injects environment variables from the `.env` file into the `devcontainer` service,
+    # making them accessible within the container's environment.
+    env_file:
+      - .env
+    environment:
+      # This must be set correctly for the `devcontainer` to be able to access the host's Docker daemon,
+      # enabling Docker-from-Docker capabilities (e.g., running Docker commands from within the `devcontainer`).
+      COMPOSE_PROJECT_NAME: ${COMPOSE_PROJECT_NAME:-react-ui}
+    init: true
+    volumes:
+      - .:/workspace:z
+      # The following volume is used to allow the `devcontainer` to access the host's Docker daemon,
+      # enabling Docker-from-Docker capabilities (e.g., running Docker commands from within the `devcontainer`).
+      - /var/run/docker.sock:/var/run/docker.sock
+      # The following named volumes persist data (e.g. terminal history, AI tools data, etc.) across container restarts.
+      # Using separate named volumes (instead of a single volume with subpaths) allows Docker to automatically
+      # seed the volume with data from the image on first use.
+      - terminal-history:/home/developer/.terminal_history
+      - claude-config:/home/developer/.config/claude
+      - claude-share:/home/developer/.local/share/claude
+      - claude-state:/home/developer/.local/state/claude
+      - copilot:/home/developer/.copilot
+      - copilot-config:/home/developer/.config/copilot
+      - opencode-config:/home/developer/.config/opencode
+      - opencode-share:/home/developer/.local/share/opencode
+      - opencode-state:/home/developer/.local/state/opencode
+
+  # This service provides Node environment and NPM
+  node:
+    build: docker/node
+    user: ${COMPOSE_UID}:${COMPOSE_GID}
+    entrypoint: sh -c 'if [ "$$COMPOSE_AUTOSTART" = "true" ]; then sh scripts/auto-start-node.sh; else sleep infinity; fi'
+    env_file:
+      - .env
+    volumes:
+      - .:/workspace:z
+
+  # This service provides Playwright environment and tools for browser automation and testing
+  playwright:
+    build: docker/playwright
+    user: ${COMPOSE_UID}:${COMPOSE_GID}
+    command: sleep infinity
+    env_file:
+      - .env
+    ports:
+      - ${COMPOSE_PLAYWRIGHT_REPORT_PORT}:9323
+    volumes:
+      - .:/workspace:z
+
+  # This provides server for documentation
+  docs:
+    build: docker/mkdocs
+    user: ${COMPOSE_UID}:${COMPOSE_GID}
+    entrypoint: sh -c 'if [ "$$COMPOSE_AUTOSTART" = "true" ]; then sh scripts/auto-start-mkdocs.sh; else sleep infinity; fi'
+    env_file:
+      - .env
+    ports:
+      - ${COMPOSE_DOCS_SERVER_PORT}:8000
+    volumes:
+      - .:/workspace:z
+
+volumes:
+  # The following volumes are used to persist data (e.g. terminal history, AI tools data, etc.) across container restarts
+  terminal-history:
+  claude-config:
+  claude-share:
+  claude-state:
+  copilot:
+  copilot-config:
+  opencode-config:
+  opencode-share:
+  opencode-state:

docker-compose.yml.dist

@@ -0,0 +1,42 @@
+services:
+  # This service is responsible for providing the main development environment for developers
+  devcontainer:
+    extends:
+      file: docker-compose.base.yml
+      service: devcontainer
+    # Use `build` when you want to customize the devcontainer using `docker/react_ui_devcontainer_local/Dockerfile`
+    # build:
+    #   context: ./docker/react_ui_devcontainer_local/
+    #   dockerfile: Dockerfile
+    # Use `image` when you want to use the default devcontainer
+    image: react-ui_devcontainer
+
+  # This service provides Node environment and NPM
+  node:
+    extends:
+      file: docker-compose.base.yml
+      service: node
+
+  # This service provides Playwright environment and tools for browser automation and testing
+  playwright:
+    extends:
+      file: docker-compose.base.yml
+      service: playwright
+
+  # This provides server for documentation
+  docs:
+    extends:
+      file: docker-compose.base.yml
+      service: docs
+
+volumes:
+  # The following volumes are used to persist data (e.g. terminal history, AI tools data, etc.) across container restarts
+  terminal-history:
+  claude-config:
+  claude-share:
+  claude-state:
+  copilot:
+  copilot-config:
+  opencode-config:
+  opencode-share:
+  opencode-state:

docker/build-docker-images.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+
+set -e
+trap 'echo "Failed to build Docker images"; exit 1' ERR
+
+cd "$(dirname "$0")"
+
+echo "Building Docker images..."
+
+if [ ! -f ../.env ]; then
+  echo "Error: .env file not found in the project root"
+  exit 1
+fi
+
+PROJECT_NAME=$(grep -E '^COMPOSE_PROJECT_NAME=' ../.env | cut -d '=' -f 2-)
+PROJECT_DEVCONTAINER_IMAGE="${PROJECT_NAME}_devcontainer"
+
+echo "Building Docker image $PROJECT_DEVCONTAINER_IMAGE..."
+docker build -t "$PROJECT_DEVCONTAINER_IMAGE" -f ./react_ui_devcontainer/Dockerfile ./react_ui_devcontainer/
+
+cd ..
+
+echo "Building project Docker images using docker-compose..."
+docker compose build
+
+echo "All Docker images built successfully!"

docker/mkdocs/Dockerfile

@@ -1,3 +1,5 @@
-FROM            squidfunk/mkdocs-material:9
+# We freezed the version of mkdocs-material to prevent issue with live reload
+# See <https://github.com/squidfunk/mkdocs-material/issues/8478>
+FROM            squidfunk/mkdocs-material:9.6.20
 RUN             mkdir /workspace
 WORKDIR         /workspace