From 8e08c77d1e1fa0edc771f4318e185ec2310181d6 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 27 Jul 2026 08:11:43 +0000 Subject: [PATCH 1/7] revert deleted changelog entries --- CHANGELOG.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bbe52b5a4..96891f15b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,10 @@ ENHANCEMENTS: * Add Windows Server 2025 image support to Guacamole. ([#4890](https://github.com/microsoft/AzureTRE/issues/4890)) * Add support for setting resource processor VMSS SKU via environment variables ([#4936](https://github.com/microsoft/AzureTRE/issues/4936)) * Exclude recovery service vaults from e2e tests ([#4920](https://github.com/microsoft/AzureTRE/issues/4920)) +* Update API, CLI, and UI dependencies to address high-severity Dependabot alerts, including `PyJWT`, `Vite`, `lodash`, `fast-uri`, `flatted`, `immutable`, and `minimatch`. +* Update dependencies to address Dependabot security alerts: `aiohttp` to 3.14.1, `Pygments` to 2.20.0, `esbuild`, `ws`, `js-yaml`, `@babel/core`, `flatted` (via vitest upgrade), and `react-router-dom`. ([#4950](https://github.com/microsoft/AzureTRE/issues/4950)) +* Added support for formatting UI code via `pre-commit` and fixed existing formatting issues. ([#4955](https://github.com/microsoft/AzureTRE/issues/4955)) +* Updated the version of `super-linter` used in the `build_validation_develop` workflow ([#4957](https://github.com/microsoft/AzureTRE/issues/4957)) BUG FIXES: * Fix Nexus shared service security: fetch admin password from Key Vault at runtime via managed identity (IMDS) instead of embedding it in the VM Run Command script content. Fix `deploy_nexus_container.sh` short-circuit path to fail loudly if the container does not start. (`sonatype-nexus` 3.10.0) ([#4983](https://github.com/microsoft/AzureTRE/pull/4983)) @@ -41,7 +45,7 @@ ENHANCEMENTS: BUG FIXES: * Fix OpenAPI/schema sample generation for `get_sample_operation` step parameters. ([#4864](https://github.com/microsoft/AzureTRE/issues/4864)) * Fix test airlock request sample data fields and enum values. ([#4866](https://github.com/microsoft/AzureTRE/issues/4866)) -* Fix property substitution not occuring where there is only a main step in the pipeline ([#4824](https://github.com/microsoft/AzureTRE/issues/4824)) +* Fix property substitution not occurring where there is only a main step in the pipeline ([#4824](https://github.com/microsoft/AzureTRE/issues/4824)) * Fix Mysql template ignored storage_mb ([#4846](https://github.com/microsoft/AzureTRE/issues/4846)) * Fix duplicate `TOPIC_SUBSCRIPTION_NAME` in `core/terraform/airlock/airlock_processor.tf` ([#4847](https://github.com/microsoft/AzureTRE/pull/4847)) * Fix Nexus repository access blocked by unaccepted EULA in Nexus 3.77+ Community Edition ([#4842](https://github.com/microsoft/AzureTRE/issues/4842)) @@ -103,7 +107,7 @@ BUG FIXES: * Fix Azure Health Data Services deployment failures by upgrading AzureRM provider to 4.58.0, switching to RBAC group assignments, and adding workspace group parameter mappings ([#4844](https://github.com/microsoft/AzureTRE/issues/4844)) * Replace deprecated `--username` flag with `--client-id` in `az login --identity` commands across all Porter bundles ([#4817](https://github.com/microsoft/AzureTRE/issues/4817)) * Fix deleted workspaces still accessible via URL - get_*_by_id methods now filter out deleted resources ([#4785](https://github.com/microsoft/AzureTRE/issues/4785)) -* Fix circular dependancy in base workspace. ([#4756](https://github.com/microsoft/AzureTRE/pull/4756)) +* Fix circular dependency in base workspace. ([#4756](https://github.com/microsoft/AzureTRE/pull/4756)) * Replaced deprecated `datetime.utcnow()` with `datetime.now(datetime.UTC)` in the API and airlock processor. ([#4743](https://github.com/microsoft/AzureTRE/issues/4743)) * Updated error messages when publishing a template version that is lower than the existing version. ([#4685](https://github.com/microsoft/AzureTRE/issues/4685)) * Disable public access on stweb storage account ([#4766](https://github.com/microsoft/AzureTRE/issues/4766)) @@ -701,7 +705,7 @@ BUG FIXES: * Airlock: Creating an import/export request causes a routing error ([#3830](https://github.com/microsoft/AzureTRE/issues/3830)) * Fix registration of templates with no 'authorizedRoles' or 'required' defined ([#3849](https://github.com/microsoft/AzureTRE/pull/3849)) * Update terraform for services bus to move network rules into namespace resource to avoid depreciation warning, and update setup_local_debugging.sh to use network_rule_sets ([#3858](https://github.com/microsoft/AzureTRE/pull/3858)) -* Update terraform MySQL resources to MySQL Flexible resources to fix depricating recources. ([#3892](https://github.com/microsoft/AzureTRE/pull/3892)) +* Update terraform MySQL resources to MySQL Flexible resources to fix deprecating resources. ([#3892](https://github.com/microsoft/AzureTRE/pull/3892)) * Fix issue with firewall failing to deploy on a new TRE deploy ([#3775](https://github.com/microsoft/AzureTRE/issues/3775)) COMPONENTS: From bf023b59e042907420d6e37b011d29044a9c4aa8 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 27 Jul 2026 08:14:03 +0000 Subject: [PATCH 2/7] add missing issue number --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 96891f15b..dd4d3d666 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,7 @@ ENHANCEMENTS: * Add Windows Server 2025 image support to Guacamole. ([#4890](https://github.com/microsoft/AzureTRE/issues/4890)) * Add support for setting resource processor VMSS SKU via environment variables ([#4936](https://github.com/microsoft/AzureTRE/issues/4936)) * Exclude recovery service vaults from e2e tests ([#4920](https://github.com/microsoft/AzureTRE/issues/4920)) -* Update API, CLI, and UI dependencies to address high-severity Dependabot alerts, including `PyJWT`, `Vite`, `lodash`, `fast-uri`, `flatted`, `immutable`, and `minimatch`. +* Update API, CLI, and UI dependencies to address high-severity Dependabot alerts, including `PyJWT`, `Vite`, `lodash`, `fast-uri`, `flatted`, `immutable`, and `minimatch`. ([#4914](https://github.com/microsoft/AzureTRE/issues/4914)) * Update dependencies to address Dependabot security alerts: `aiohttp` to 3.14.1, `Pygments` to 2.20.0, `esbuild`, `ws`, `js-yaml`, `@babel/core`, `flatted` (via vitest upgrade), and `react-router-dom`. ([#4950](https://github.com/microsoft/AzureTRE/issues/4950)) * Added support for formatting UI code via `pre-commit` and fixed existing formatting issues. ([#4955](https://github.com/microsoft/AzureTRE/issues/4955)) * Updated the version of `super-linter` used in the `build_validation_develop` workflow ([#4957](https://github.com/microsoft/AzureTRE/issues/4957)) From ac42fb811016611898b2ff25197cc39cfdf65cea Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 27 Jul 2026 08:26:56 +0000 Subject: [PATCH 3/7] Update changelog to reflect dependency updates addressing high-severity Dependabot alerts --- CHANGELOG.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dd4d3d666..9b20d6e77 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,8 +12,6 @@ ENHANCEMENTS: * Add Windows Server 2025 image support to Guacamole. ([#4890](https://github.com/microsoft/AzureTRE/issues/4890)) * Add support for setting resource processor VMSS SKU via environment variables ([#4936](https://github.com/microsoft/AzureTRE/issues/4936)) * Exclude recovery service vaults from e2e tests ([#4920](https://github.com/microsoft/AzureTRE/issues/4920)) -* Update API, CLI, and UI dependencies to address high-severity Dependabot alerts, including `PyJWT`, `Vite`, `lodash`, `fast-uri`, `flatted`, `immutable`, and `minimatch`. ([#4914](https://github.com/microsoft/AzureTRE/issues/4914)) -* Update dependencies to address Dependabot security alerts: `aiohttp` to 3.14.1, `Pygments` to 2.20.0, `esbuild`, `ws`, `js-yaml`, `@babel/core`, `flatted` (via vitest upgrade), and `react-router-dom`. ([#4950](https://github.com/microsoft/AzureTRE/issues/4950)) * Added support for formatting UI code via `pre-commit` and fixed existing formatting issues. ([#4955](https://github.com/microsoft/AzureTRE/issues/4955)) * Updated the version of `super-linter` used in the `build_validation_develop` workflow ([#4957](https://github.com/microsoft/AzureTRE/issues/4957)) @@ -23,8 +21,8 @@ BUG FIXES: * Fix API timeout and name collision failures on workspace creation by checking storage account name availability and improved logging. ([#4946](https://github.com/microsoft/AzureTRE/pull/4946)) * Fix error handling in airlock processor ([#4929](https://github.com/microsoft/AzureTRE/pull/4929)) * Update allowed URLs in Nexus for letsencrypt ([#4899](https://github.com/microsoft/AzureTRE/pull/4899)) -* Fix dependabot high severity alerts for packages fast-uri, lodash, picomatch, immutable, minimatch, flatted and PyJWT -* Fix dependabot high moderate alerts for packages aiohttp and pytest, pytest-asyncio +* Update API, CLI, and UI dependencies to address high-severity Dependabot alerts, including `PyJWT`, `Vite`, `lodash`, `fast-uri`, `flatted`, `immutable`, and `minimatch`. ([#4914](https://github.com/microsoft/AzureTRE/issues/4914)) +* Update dependencies to address Dependabot security alerts: `aiohttp` to 3.14.1, `Pygments` to 2.20.0, `esbuild`, `ws`, `js-yaml`, `@babel/core`, `flatted` (via vitest upgrade), and `react-router-dom`. ([#4950](https://github.com/microsoft/AzureTRE/issues/4950)) * Fix spelling in docs using codespell ([#4954](https://github.com/microsoft/AzureTRE/issues/4954)) * Fix issues identified by flake8 ([#4958](https://github.com/microsoft/AzureTRE/issues/4958)) * Replace deprecated yaspell with codespell and add pre-commit hook installer to devcontainer. ([#4953](https://github.com/microsoft/AzureTRE/issues/4953)) From 2db7d18916ca490904cf92da842b11949c2844e6 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 27 Jul 2026 08:32:38 +0000 Subject: [PATCH 4/7] Update changelog to reflect dependency updates addressing security alerts --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b20d6e77..e6c154095 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,7 +22,7 @@ BUG FIXES: * Fix error handling in airlock processor ([#4929](https://github.com/microsoft/AzureTRE/pull/4929)) * Update allowed URLs in Nexus for letsencrypt ([#4899](https://github.com/microsoft/AzureTRE/pull/4899)) * Update API, CLI, and UI dependencies to address high-severity Dependabot alerts, including `PyJWT`, `Vite`, `lodash`, `fast-uri`, `flatted`, `immutable`, and `minimatch`. ([#4914](https://github.com/microsoft/AzureTRE/issues/4914)) -* Update dependencies to address Dependabot security alerts: `aiohttp` to 3.14.1, `Pygments` to 2.20.0, `esbuild`, `ws`, `js-yaml`, `@babel/core`, `flatted` (via vitest upgrade), and `react-router-dom`. ([#4950](https://github.com/microsoft/AzureTRE/issues/4950)) +* Update dependencies to address Dependabot security alerts: `aiohttp`, `pytest`, `pytest-asyncio`, `Pygments`, `esbuild`, `ws`, `js-yaml`, `@babel/core`, `flatted` (via vitest upgrade), and `react-router-dom`. ([#4915](https://github.com/microsoft/AzureTRE/issues/4915), [#4950](https://github.com/microsoft/AzureTRE/issues/4950)) * Fix spelling in docs using codespell ([#4954](https://github.com/microsoft/AzureTRE/issues/4954)) * Fix issues identified by flake8 ([#4958](https://github.com/microsoft/AzureTRE/issues/4958)) * Replace deprecated yaspell with codespell and add pre-commit hook installer to devcontainer. ([#4953](https://github.com/microsoft/AzureTRE/issues/4953)) From 47b6a8bc05e6900a4f5bcbb2d881514fe6553ad2 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 27 Jul 2026 08:35:18 +0000 Subject: [PATCH 5/7] Update changelog to reflect enhancements in UI code formatting and super-linter version --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e6c154095..2f3b12231 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,8 +12,8 @@ ENHANCEMENTS: * Add Windows Server 2025 image support to Guacamole. ([#4890](https://github.com/microsoft/AzureTRE/issues/4890)) * Add support for setting resource processor VMSS SKU via environment variables ([#4936](https://github.com/microsoft/AzureTRE/issues/4936)) * Exclude recovery service vaults from e2e tests ([#4920](https://github.com/microsoft/AzureTRE/issues/4920)) -* Added support for formatting UI code via `pre-commit` and fixed existing formatting issues. ([#4955](https://github.com/microsoft/AzureTRE/issues/4955)) -* Updated the version of `super-linter` used in the `build_validation_develop` workflow ([#4957](https://github.com/microsoft/AzureTRE/issues/4957)) +* Add support for formatting UI code via `pre-commit` and fixed existing formatting issues. ([#4955](https://github.com/microsoft/AzureTRE/issues/4955)) +* Update the version of `super-linter` used in the `build_validation_develop` workflow to 8.7.0 ([#4957](https://github.com/microsoft/AzureTRE/issues/4957)) BUG FIXES: * Fix Nexus shared service security: fetch admin password from Key Vault at runtime via managed identity (IMDS) instead of embedding it in the VM Run Command script content. Fix `deploy_nexus_container.sh` short-circuit path to fail loudly if the container does not start. (`sonatype-nexus` 3.10.0) ([#4983](https://github.com/microsoft/AzureTRE/pull/4983)) From 033e5512585d4beae7b4ab4fdccbce8b2cf9e178 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 27 Jul 2026 08:52:36 +0000 Subject: [PATCH 6/7] changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2f3b12231..e673ccbe0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,7 @@ ENHANCEMENTS: * Add Windows Server 2025 image support to Guacamole. ([#4890](https://github.com/microsoft/AzureTRE/issues/4890)) * Add support for setting resource processor VMSS SKU via environment variables ([#4936](https://github.com/microsoft/AzureTRE/issues/4936)) * Exclude recovery service vaults from e2e tests ([#4920](https://github.com/microsoft/AzureTRE/issues/4920)) -* Add support for formatting UI code via `pre-commit` and fixed existing formatting issues. ([#4955](https://github.com/microsoft/AzureTRE/issues/4955)) +* Add support for formatting UI code via `pre-commit` and fix existing formatting issues. ([#4955](https://github.com/microsoft/AzureTRE/issues/4955)) * Update the version of `super-linter` used in the `build_validation_develop` workflow to 8.7.0 ([#4957](https://github.com/microsoft/AzureTRE/issues/4957)) BUG FIXES: From 0d7db04b7533d3f62dca485fb9564510893bac71 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 27 Jul 2026 14:21:12 +0000 Subject: [PATCH 7/7] Add documentation build and serve commands; update contributing guide --- CHANGELOG.md | 1 + Makefile | 10 +++++- devops/scripts/docs.sh | 72 ++++++++++++++++++++++++++++++++++++++++++ docs/contributing.md | 25 +++++++++++++++ 4 files changed, 107 insertions(+), 1 deletion(-) create mode 100755 devops/scripts/docs.sh diff --git a/CHANGELOG.md b/CHANGELOG.md index e673ccbe0..4bfabbc10 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,7 @@ ENHANCEMENTS: * Exclude recovery service vaults from e2e tests ([#4920](https://github.com/microsoft/AzureTRE/issues/4920)) * Add support for formatting UI code via `pre-commit` and fix existing formatting issues. ([#4955](https://github.com/microsoft/AzureTRE/issues/4955)) * Update the version of `super-linter` used in the `build_validation_develop` workflow to 8.7.0 ([#4957](https://github.com/microsoft/AzureTRE/issues/4957)) +* Add `make docs` to build and preview documentation ([#5007](https://github.com/microsoft/AzureTRE/issues/5007)) BUG FIXES: * Fix Nexus shared service security: fetch admin password from Key Vault at runtime via managed identity (IMDS) instead of embedding it in the VM Run Command script content. Fix `deploy_nexus_container.sh` short-circuit path to fail loudly if the container does not start. (`sonatype-nexus` 3.10.0) ([#4983](https://github.com/microsoft/AzureTRE/pull/4983)) diff --git a/Makefile b/Makefile index aab487b2c..ccee2de50 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: bootstrap-init mgmt-deploy mgmt-destroy build-api-image push-api-image tre-deploy tre-destroy letsencrypt +.PHONY: bootstrap-init mgmt-deploy mgmt-destroy build-api-image push-api-image tre-deploy tre-destroy letsencrypt docs .DEFAULT_GOAL := help SHELL:=/bin/bash @@ -265,6 +265,14 @@ lint: ## 🧹 Lint all files lint-docs: LINTER_REGEX_INCLUDE='./docs/.*\|./mkdocs.yml' $(MAKE) lint +# Description: Documentation helper target +# Single target `make docs` will install deps and serve the site locally (default). Set MODE=build for build-only mode. +# Example: make docs -> installs deps and serves site locally +# Example: make docs MODE=build -> installs deps and builds site only +docs: ## Install docs deps and build/serve the MkDocs site + @bash ./devops/scripts/docs.sh $(MODE) + + # Description: Build the bundle with Porter. # # check-params is called at the end since it needs the bundle image, # # so we build it first and then run the check. diff --git a/devops/scripts/docs.sh b/devops/scripts/docs.sh new file mode 100755 index 000000000..163a731e6 --- /dev/null +++ b/devops/scripts/docs.sh @@ -0,0 +1,72 @@ +#!/usr/bin/env bash +set -euo pipefail + +PY=python3 +VENV=.venv +REQS=docs/requirements.txt + +PORT=${PORT:-8000} + +usage(){ + echo "Usage: $0 [build|serve|install]" >&2 + exit 2 +} + +if [ "$#" -gt 1 ]; then + usage +fi + +CMD=${1:-serve} + +if [ ! -f "$REQS" ]; then + echo "Requirements file not found: $REQS" >&2 + exit 1 +fi + +if [ ! -d "$VENV" ]; then + echo "Creating virtualenv at $VENV" + $PY -m venv "$VENV" +fi + +# shellcheck disable=SC1091 +source "$VENV/bin/activate" + +pip install --upgrade pip +pip install -r "$REQS" + +get_free_port() { + local start_port="${1:-8000}" + "$PY" -c " +import socket +start = $start_port +for p in range(start, start + 100): + with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: + try: + s.bind(('127.0.0.1', p)) + print(p) + break + except OSError: + continue +" +} + +case "$CMD" in + build) + echo "Building mkdocs site..." + "$VENV/bin/mkdocs" build --strict + ;; + serve) + FREE_PORT=$(get_free_port "$PORT") + if [ "$FREE_PORT" != "$PORT" ]; then + echo "Port $PORT is in use. Using next available port: $FREE_PORT" + fi + echo "Starting mkdocs serve (http://127.0.0.1:${FREE_PORT})..." + "$VENV/bin/mkdocs" serve -a "127.0.0.1:${FREE_PORT}" + ;; + install) + echo "Installed documentation dependencies into $VENV" + ;; + *) + usage + ;; +esac diff --git a/docs/contributing.md b/docs/contributing.md index 888983d1b..6aaacaf45 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -28,4 +28,29 @@ * [Report an Issue or Make a Suggestion](https://github.com/microsoft/AzureTRE/issues/new/choose) +## Building and Serving Documentation Locally + +To preview and test changes to the documentation site locally: + +* **Serve documentation locally (default)**: + ```bash + make docs + ``` + This installs required dependencies, selects the first available port (starting at `8000`), and starts the local MkDocs server. + + You can also specify a custom port: + ```bash + PORT=8100 make docs + ``` + +* **Build documentation (build-only)**: + ```bash + make docs MODE=build + ``` + +* **Lint documentation files**: + ```bash + make lint-docs + ``` + Thanks! :heart: :heart: :heart: