[NDR-324] Add dev container (#927)

Co-authored-by: Kris Bloe <[email protected]>

Author: matthewpotter2-nhs

.devcontainer/Dockerfile

@@ -0,0 +1,43 @@
+FROM --platform=linux/amd64 mcr.microsoft.com/devcontainers/python:3.11
+
+RUN apt-get update && apt-get upgrade -y && apt-get install -y \
+      git \
+      jq \
+      rsync \
+      tree \
+      unzip \
+      wget \
+      strip-nondeterminism \
+      uuid-runtime \
+      parallel \
+      bc
+
+# Install Node.js (needed for Cypress)
+RUN apt-get update && apt-get install -y curl gnupg && \
+    curl -fsSL https://deb.nodesource.com/setup_24.x | bash - && \
+    apt-get install -y nodejs
+
+# Install Cypress GUI dependencies
+RUN apt-get install -y \
+    xvfb \
+    libgtk-3-0 \
+    libnss3 \
+    libatk1.0-0 \
+    libatk-bridge2.0-0 \
+    libasound2
+
+RUN wget https://github.com/mikefarah/yq/releases/download/v4.48.2/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+RUN wget https://github.com/asdf-vm/asdf/releases/download/v0.18.0/asdf-v0.18.0-linux-amd64.tar.gz -O - | tar xz && sudo mv asdf /usr/local/bin/asdf
+
+# Install Cypress globally
+RUN npm install -g [email protected]
+
+# Installing ASDF
+USER vscode
+RUN echo "export ASDF_DATA_DIR=/home/vscode/.asdf" >> ~/.bashrc
+RUN echo ". <(asdf completion bash)"  >> ~/.bashrc
+
+# Install poetry
+RUN curl -sSL https://install.python-poetry.org | POETRY_VERSION=2.2.1 python3
+
+# ASDF and poetry added to path in devcontainer.json

.devcontainer/devcontainer.json

@@ -0,0 +1,57 @@
+{
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  "containerEnv": {
+    "AWS_VAULT_BACKEND": "file",
+    "AWS_VAULT_FILE_PASSPHRASE": "default"
+  },
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2.12.4": {
+      "moby": false,
+      "version": "latest",
+      "dockerDashComposeVersion": "latest"
+    }
+  },
+  "remoteEnv": {
+    "PATH": "${containerEnv:PATH}:/home/vscode/.asdf:/home/vscode/.asdf/shims:/home/vscode/.local/bin"
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.black-formatter",
+        "ms-python.mypy-type-checker",
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "4ops.terraform",
+        "maattdd.gitless",
+        "ms-python.python",
+        "rogalmic.bash-debug",
+        "sidp.strict-whitespace",
+        "streetsidesoftware.code-spell-checker",
+        "tamasfe.even-better-toml",
+        "timonwong.shellcheck",
+        "hashicorp.terraform",
+        "GitHub.copilot",
+        "GitHub.copilot-chat",
+        "LittleFoxTeam.vscode-python-test-adapter",
+        "charliermarsh.ruff",
+        "github.vscode-github-actions",
+        "esbenp.prettier-vscode"
+      ],
+      "settings": {}
+    }
+  },
+  "mounts": [
+    "source=${env:HOME}${env:USERPROFILE}/.aws,target=/home/vscode/.aws,type=bind",
+    "source=${localEnv:HOME}/.ssh,target=/home/vscode/.ssh,type=bind,consistency=cached",
+    "source=${localEnv:HOME}/.gnupg,target=/home/vscode/.gnupg,type=bind,consistency=cached"
+  ],
+  "postCreateCommand": "HOST_PWD=${localWorkspaceFolder} bash -c '.devcontainer/src/create.sh' ",
+
+"runArgs": [
+  "-e", "DISPLAY",
+  "-v", "/tmp/.X11-unix:/tmp/.X11-unix",
+  "--platform=linux/amd64"
+]
+}

.devcontainer/src/create.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+
+echo "Installing ASDF plugins and tools defined in .tool-versions."
+echo "If this is the first time you've launched this devcontainer it might take a little while."
+echo
+
+# Install all the asdf plugins needed for tooling in the .tool-versions file.
+make install-dev
+
+# Add MOTD style helper
+BASENAME=$(basename "$HOST_PWD")
+echo -e "\n. /workspaces/$BASENAME/.devcontainer/src/motd.sh\n" | tee -a ~/.bashrc ~/.profile
+echo 'alias av="aws-vault"' | tee -a ~/.bashrc ~/.profile
+
+# Required for code signing and is in '' to delay evaluation intentionally
+# shellcheck disable=SC2016
+echo 'export GPG_TTY=$(tty)' | tee -a ~/.bashrc ~/.profile
+
+# Preserve/append history across subshells
+echo 'shopt -s histappend' | tee -a ~/.bashrc ~/.profile
+echo "PROMPT_COMMAND='history -a'" | tee -a ~/.bashrc ~/.profile

.devcontainer/src/motd.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# shellcheck disable=SC1003,SC2028
+check_aws_authentication() {
+    caller_identity=$(aws sts get-caller-identity 2>/dev/null)
+
+    if [[ -z "$caller_identity" ]]; then
+        echo "No valid session. Please make sure the devcontainer was run with authorised AWS STS session"
+        echo
+    fi
+
+    echo "Valid AWS CLI session for AWS account: $(aws sts get-caller-identity | jq -r '.Account')"
+    return 0
+}
+
+echo '  __    _ _____  _____   '
+echo ' |  \  | |  __ \|  _  \  '
+echo ' | \ \ | | |  | | | \  | '
+echo ' |  \ \| | |  | | |_/ /  '
+echo ' | | \   | |__| | | \ \  '
+echo ' |_|  \__|_____/|_|  \_\ '
+echo '                         '
+echo "You can list configured AWS profiles like this:"
+echo "  'aws-vault list'"
+echo
+echo "Export the AWS Environment Variables for a your session like this:"
+echo "  'aws-vault exec replace-this-with-my-aws-profile'"
+echo
+echo "If your session times out, simply exit the subshell and do it again:"
+echo "  'exit'"
+echo "  'aws-vault exec replace-this-with-my-aws-profile'"
+echo

.tool-versions

@@ -0,0 +1,12 @@
+python 3.11.11
+aws-vault 7.2.0
+awscli 2.28.17
+gitleaks 8.28.0
+shellcheck 0.11.0
+terraform 1.13.0
+terraform-docs 0.20.0
+trivy 0.65.0
+nodejs 24.6.0
+pre-commit 4.3.0
+poetry 2.2.1
+awsume 4.5.4

Makefile

@@ -16,6 +16,9 @@ LAMBDA_LAYER_PYTHON_PATH=python/lib/python$(PYTHON_VERSION)/site-packages
 
 ZIP_BASE_PATH = ./$(LAMBDAS_BUILD_PATH)/$(lambda_name)/tmp
 ZIP_COMMON_FILES = lambdas/utils lambdas/models lambdas/services lambdas/repositories lambdas/enums lambdas/scripts
+CONTAINER ?= false
+
+.PHONY: install clean help format list requirements ruff
 
 default: help
 
@@ -70,33 +73,62 @@ download-api-certs: ## Downloads mTLS certificates (use with dev envs only). Usa
 	./scripts/aws/download-api-certs.sh $(WORKSPACE)
 
 test-api-e2e:
+ifeq ($(CONTAINER), true)
+	cd ./lambdas && PYTHONPATH=. poetry run pytest tests/e2e/api --ignore=tests/e2e/api/fhir -vv
+else
 	cd ./lambdas && ./venv/bin/python3 -m pytest tests/e2e/api --ignore=tests/e2e/api/fhir -vv
+endif
 
-test-fhir-api-e2e: ## Runs FHIR API E2E tests. Usage: make test-fhir-api-e2e WORKSPACE=<workspace>
-	./scripts/test/run-e2e-fhir-api-tests.sh --workspace $(WORKSPACE)
+test-fhir-api-e2e: ## Runs FHIR API E2E tests. Usage: make test-fhir-api-e2e WORKSPACE=<workspace> CONTAINER=<true|false>
+	./scripts/test/run-e2e-fhir-api-tests.sh --workspace $(WORKSPACE) --container $(CONTAINER)
 	rm -rf ./lambdas/mtls_env_certs/$(WORKSPACE)
 
 test-apim-e2e: ## Runs APIM E2E tests for National Document Repository FHIR R4 API against ndr-dev.
-	./scripts/test/run-apim-e2e-tests.sh
+	./scripts/test/run-apim-e2e-tests.sh --container $(CONTAINER)
 
 test-api-e2e-snapshots:
+ifeq ($(CONTAINER), true)
+	cd ./lambdas && PYTHONPATH=. poetry run pytest tests/e2e/api --ignore=tests/e2e/api/fhir --snapshot-update
+else
 	cd ./lambdas && ./venv/bin/python3 -m pytest tests/e2e/api --ignore=tests/e2e/api/fhir --snapshot-update
+endif
 
 test-bulk-upload-e2e:
+ifeq ($(CONTAINER), true)
+	cd ./lambdas && PYTHONPATH=. poetry run pytest tests/e2e/bulk_upload -vv
+else
 	cd ./lambdas && ./venv/bin/python3 -m pytest tests/e2e/bulk_upload -vv
+endif
 
 test-unit:
+ifeq ($(CONTAINER), true)
+	cd ./lambdas && \
+	PYTHONPATH=. poetry run pytest tests/unit ../scripts/github/checklist_validator/tests
+else
 	cd ./lambdas && \
 	PYTHONPATH=.. ./venv/bin/python3 -m pytest tests/unit ../scripts/github/checklist_validator/tests
+endif
 
 test-unit-coverage:
+ifeq ($(CONTAINER), true)
+	cd ./lambdas && PYTHONPATH=. poetry run pytest tests/unit --cov=. --cov-report xml:coverage.xml
+else
 	cd ./lambdas && ./venv/bin/python3 -m pytest tests/unit --cov=. --cov-report xml:coverage.xml
+endif
 
 test-unit-coverage-html:
+ifeq ($(CONTAINER), true)
+	cd ./lambdas && poetry run coverage run --source=. --omit="tests/*" -m pytest -v tests/unit && coverage report && coverage html
+else
 	cd ./lambdas && coverage run --source=. --omit="tests/*" -m pytest -v tests/unit && coverage report && coverage html
+endif
 
 test-unit-collect:
+ifeq ($(CONTAINER), true)
+	cd ./lambdas && PYTHONPATH=. poetry run pytest tests/unit --collect-only
+else
 	cd ./lambdas && ./venv/bin/python3 -m pytest tests/unit --collect-only
+endif
 
 env:
 	@echo "Removing old venv."
@@ -164,6 +196,23 @@ install-pdfjs:
 	unzip -o -d ./app/public/pdfjs ./app/public/pdfjs/pdfjs.zip
 	rm ./app/public/pdfjs/pdfjs.zip
 
+# Environment tooling targets:
+install-asdf:
+	echo "Setting up ASDF and related dependencies"
+	cut -d ' ' -f1 .tool-versions | xargs -I {} asdf plugin add {} || true
+	asdf install
+
+install-poetry:
+	echo "Installing all poetry dependencies to local environment"
+	poetry install
+
+	echo "Generating 'requirements.txt' files"
+	$(MAKE) requirements
+
+install-dev: install-asdf install-poetry install-cypress
+	git config --unset-all core.hooksPath || true
+	pre-commit install --config src/config/pre-commit.yml --install-hooks
+
 start:
 	npm --prefix ./app start
 
@@ -189,11 +238,13 @@ docker-down:
 	docker-compose -f ./app/docker-compose.yml down
 
 cypress-open:
-	TZ=GMT npm --prefix ./app run cypress
+	xvfb-run -- npm --prefix ./app run cypress
 
 cypress-run:
-	TZ=GMT npm --prefix ./app run cypress-run
+	xvfb-run -- npm --prefix ./app run cypress-run
 
 cypress-report:
-	TZ=GMT npm --prefix ./app run cypress-report
+	xvfb-run -- npm --prefix ./app run cypress-report
 
+install-cypress:
+	npm install --save-dev cypress

README.md

@@ -6,20 +6,61 @@
 - [React User Interface README.md](app/README.md).
 - [E2E test README.md](lambdas/tests/e2e/README.md) (we have E2E tests for our FHIR endpoints and APIM setup).
 
-## Installation
+## Running Locally
+
+The dev container option standardises tools for both python (via poetry) and node via asdf.
+
+> [!WARNING]
+> Once you have the dev container running, you will need to install your git credentials for signing your commits.
+
+<!-- -->
+> If the dev container build errors on docker, check your config at `~/.docker/config.json`, which should have something similar to:
+>
+> ```json
+> {
+>     "auths": {}
+> }
+> ```
+>
+> Remove any lines that mention `desktop`.
+
+### Pre-requisites
+
+The following tools are required for all options:
 
 - [Git](https://git-scm.com/)
+- Docker (e.g. via [Brew](https://formulae.brew.sh/formula/docker))
+
+### Method 1 - Dev container within VS Code (recommended)
+
+> [!IMPORTANT]
+> This **will not work** within a VS Code Workspace.
+
+1. Install the `Dev Containers` VSCode extension.
+1. Press `Ctrl+Shift+P`.
+1. Select `Dev Containers: Rebuild and Reopen in Container`.
+
+### Method 2 - Dev container (not using VS Code)
+
+If you don't use VSCode, run the following commands:
+
+```bash
+npm install -g @devcontainers/cli
+devcontainer build --workspace-folder .
+devcontainer up --workspace-folder .
+devcontainer exec --workspace-folder . bash
+```
+
+### Method 3 - Manual installation
+
 - [Terraform](https://formulae.brew.sh/formula/terraform)
-- [docker](https://formulae.brew.sh/formula/docker)
 - [docker-compose](https://formulae.brew.sh/formula/docker-compose)
 - [AWS CLI](https://aws.amazon.com/cli/)
 - [Awsume](https://formulae.brew.sh/formula/awsume)
 - [ruff](https://formulae.brew.sh/formula/ruff)
 - [Node@24](https://formulae.brew.sh/formula/node@24)
 - [[email protected]](https://formulae.brew.sh/formula/[email protected])
 
-_Note: It is recommended to use [Homebrew](https://brew.sh/) to install most of these._
-
 ## Monitoring
 
 We have configured AWS CloudWatch to provide alarm notifications whenever one of a number of metrics exceeds its normal

lambdas/tests/e2e/README.md

@@ -36,6 +36,10 @@ output=json
 
 Make sure your AWS profile has access to the required resources.
 
+## Using the dev container
+
+All of the below make commands can be used in the dev container. To run the below commands you need to append `CONTAINER=true`.
+
 ## 🔧 Available Make Commands
 
 - `make test-fhir-api-e2e WORKSPACE=<workspace>` — Runs the FHIR API E2E tests with mTLS against a given workspace