fixup! fixup! fixup! fixup! fixup! fixup! fixup! fixup! fixup! fixup! fixup! !fixup Introduce devcontainer service container based development environment (#705)

Author: bedrich-schindler

.env.dist

@@ -7,16 +7,14 @@
 COMPOSE_PROJECT_NAME=react-ui
 
 # Docker compose ports for Docs server instances
-COMPOSE_START_DOCS_SERVER_PORT=8000
+COMPOSE_DOCS_SERVER_PORT=8000
 
 # Docker compose ports for Playwright Component Testing report server
 COMPOSE_PLAYWRIGHT_REPORT_PORT=9323
 
-# Flag whether to start JavaScript files watcher at container start
-COMPOSE_START_JS_FILES_WATCHER_AT_START=true
-
-# Flag whether to start docs server at container start
-COMPOSE_START_DOCS_SERVER_AT_START=true
+# 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`

docker-compose.base.yml

@@ -48,8 +48,7 @@ services:
   node:
     build: docker/node
     user: ${COMPOSE_UID}:${COMPOSE_GID}
-    command: sleep infinity
-    entrypoint: sh -c 'if [ "$$COMPOSE_START_JS_FILES_WATCHER_AT_START" = "true" ]; then npm ci && npm start; fi'
+    entrypoint: sh -c 'if [ "$$COMPOSE_AUTOSTART" = "true" ]; then sh scripts/auto-start-node.sh; else sleep infinity; fi'
     env_file:
       - .env
     volumes:
@@ -71,12 +70,11 @@ services:
   docs:
     build: docker/mkdocs
     user: ${COMPOSE_UID}:${COMPOSE_GID}
-    command: sleep infinity
-    entrypoint: sh -c 'if [ "$$COMPOSE_START_DOCS_SERVER_AT_START" = "true" ]; then mkdocs serve; fi'
+    entrypoint: sh -c 'if [ "$$COMPOSE_AUTOSTART" = "true" ]; then sh scripts/auto-start-mkdocs.sh; else sleep infinity; fi'
     env_file:
       - .env
     ports:
-      - ${COMPOSE_START_DOCS_SERVER_PORT}:8000
+      - ${COMPOSE_DOCS_SERVER_PORT}:8000
     volumes:
       - .:/workspace:z
 

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

package.json

@@ -54,6 +54,7 @@
     "lint": "npm run eslint && npm run markdownlint && npm run stylelint",
     "markdownlint": "markdownlint-cli2 \"README.md\" \"src/**/*.md\"",
     "postbuild": "npm run copy",
+    "postinstall": "sh scripts/write-lockfile-hash.sh",
     "precopy": "rm -rf dist && mkdir dist",
     "prepublishOnly": "npm run build",
     "start": "webpack --watch --mode=development",

scripts/auto-start-mkdocs.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+
+# Start the docs server
+echo "Starting the docs server..."
+mkdocs serve

scripts/auto-start-node.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+
+set -e
+
+# File to read the hash of the package-lock.json
+LOCK_HASH_FILE="node_modules/.package-lock-hash"
+
+# Parent directory of the script
+SCRIPT_DIR="$( cd "$( dirname "$0" )" && pwd )"
+
+# Change to the parent directory of the script
+cd "$SCRIPT_DIR/.."
+
+# Install dependencies if node_modules is missing or out of date
+CURRENT_HASH=$(sha256sum package-lock.json | awk '{print $1}')
+if [ ! -d "node_modules" ]; then
+  echo "Installing dependencies (node_modules directory is missing)..."
+  npm ci
+elif [ ! -f "$LOCK_HASH_FILE" ]; then
+  echo "Installing dependencies (lockfile of package-lock.json is missing)..."
+  npm ci
+elif [ "$(cat "$LOCK_HASH_FILE")" != "$CURRENT_HASH" ]; then
+  echo "Installing dependencies (package-lock.json has changed)..."
+  npm ci
+fi
+
+# Build the application (must be run prior to starting the server to ensure the latest code is used)
+echo "Building the application..."
+npm run build
+
+# Start the application
+echo "Starting the application..."
+npm start

scripts/write-lockfile-hash.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+
+set -e
+
+# File to store the hash of the package-lock.json
+LOCK_HASH_FILE="node_modules/.package-lock-hash"
+
+# Parent directory of the script
+SCRIPT_DIR="$( cd "$( dirname "$0" )" && pwd )"
+
+# Change to the parent directory of the script
+cd "$SCRIPT_DIR/.."
+
+# Record the hash of the lockfile we just installed against
+sha256sum package-lock.json | awk '{print $1}' > "$LOCK_HASH_FILE"

src/docs/contribute/general-guidelines.md

@@ -163,6 +163,32 @@ The `devcontainer` depends on the following service containers defined in
 All service containers mount the workspace at `/workspace` so that file changes
 are shared.
 
+## Automatic Service Bootstrap
+
+> You can skip this section if you do not want to automatically
+> [install dependencies](#installing-dependencies), [build](#building), and
+> [run](#running) the application, or if you are not an experienced developer.
+
+Setting `COMPOSE_AUTOSTART=true` in `.env` makes the `node` and `docs`
+service containers automatically install dependencies, build, and run the
+application when they start. The default is `false`.
+
+Setting `COMPOSE_AUTOSTART=true` comes with the following trade-offs:
+
+* **Changes to dependencies require a container restart.** The watcher owns the
+  service container's entrypoint, so updating dependencies (e.g. pulling a
+  branch that changes `package-lock.json`, or running `npm install <pkg>`)
+  only takes effect after restarting the `node` service container. The same
+  applies to changes that affect the documentation server.
+* **Service logs are not directly visible.** The watcher and docs server run in
+  their own service containers rather than in your `devcontainer` shell, so
+  their output is not shown alongside your regular terminal work. You have to
+  inspect it via `docker compose logs <service>` from the host.
+
+> If something is not working as expected, or you are not sure what is going on,
+> set `COMPOSE_AUTOSTART=false`, restart the containers, and follow the
+> manual steps in the sections below instead.
+
 ## Installing Dependencies
 
 Run it on initial setup or when dependencies have changed:
@@ -187,9 +213,6 @@ mkdocs build
 
 ## Running
 
-> See `.env` whether both the application and documentation server are not configured
-> to auto-start on container startup. If they are, you can skip the following steps.
-
 To start building JavaScript files in watch mode:
 
 ```bash