Introduce devcontainer service container based development environment (#705)

All development is now done inside the container named `devcontainer`
which contains all necessary tools and dependencies. The devcontainer
orchestrates other service containers behind the scenes
via Docker-from-Docker. Other containers are implementation details
and should not be accessed directly.

This is breaking change commit for development environment,
so it is required to remove all the env files and start with
fresh one.

There are two supported ways to access the development environment.
Recommended way is to use Development Containers with an IDE.
The alternative is to use Docker Compose directly. Local development
is officially no more supported.

What more, documentation of contribution and CLAUDE.md was updated
to match with the changes.

Author: bedrich-schindler

.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

.env.playwright.dist

@@ -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

.gitignore

@@ -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

CLAUDE.md

@@ -0,0 +1,93 @@
+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-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-state:
+  copilot:
+  copilot-config:
+  opencode-config:
+  opencode-share:
+  opencode-state:

docker-compose.base.yml

@@ -0,0 +1,41 @@
+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-state:
+  copilot:
+  copilot-config:
+  opencode-config:
+  opencode-share:
+  opencode-state:

docker-compose.yml

@@ -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-compose.yml.dist

@@ -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