update readme

Author: anthony-nhs

README.md

@@ -3,9 +3,12 @@ EPS DEV CONTAINERS
 
 # Introduction
 This repo contains code to build a vscode devcontainers that can be used as a base image for all EPS projects.   
-Images are build for amd64 and arm64 and a manifest file created that can be pulled for both architectures.   
-Images are based on mcr.microsoft.com/devcontainers/base:ubuntu-22.04
-Images contain
+Images are build for amd64 and arm64 and a manifest file created that can be pulled for both architectures. This is then pushed to github container registry.    
+Images are built using using https://github.com/devcontainers/cli.   
+
+We build a base image based on mcr.microsoft.com/devcontainers/base:ubuntu-22.04 that other images are then based on
+
+The base image contains
  - latest os packages
  - asdf
  - aws cli
@@ -24,94 +27,130 @@ asdf install and setup for these so they are available globally as vscode user
  - ruby (for github pages)
  - trivy
 
-Install asdf plugins for all tools we use
 Install and setup git-secrets
 
+# Using the images
+In each eps project, you can put this in the devcontainer Dockerfile. You should not need to add any features. 
+```
+FROM ghcr.io/nhsdigital/eps-devcontainers/node_24_python_3_13:<version>
+
+USER root
+# specify DOCKER_GID to force container docker group id to match host
+RUN if [ -n "${DOCKER_GID}" ]; then \
+      if ! getent group docker; then \
+        groupadd -g ${DOCKER_GID} docker; \
+      else \
+        groupmod -g ${DOCKER_GID} docker; \
+      fi && \
+      usermod -aG docker vscode; \
+    fi
+
+USER vscode
+```
+
 # Project structure
-## base container
-The base dev container is defined in src/base/.devcontainer folder. This folder contains a Dockerfile and a devcontainer.json file which is used to build the container.   
-As part of the dockerfile, there are scripts in the scripts folder that run as root and vscode user that setup and install various programs.
+We have 3 types of dev container. These are defined under src
 
-The dev container is built using https://github.com/devcontainers/cli
+`base` - this is the base image that all others are based on.   
+`languages` - this installs specific versions of node and python.   
+`projects` - this is used for projects where more customization is needed than just a base language image
 
-## common files
-There are some common files under src/common. These include
-- a Dockerfile used to build specific containers that installs poetry after python has been installed
-- a .trivyignore file that contains trivy suppressions in the base image
+Each image to be built contains a .devcontainer folder that defines how the devcontainer should be built. At a minimum, this should contain a devcontainer.json file. See https://containers.dev/implementors/json_reference/ for options for this
 
-## specific containers
-There are specific containers in src/<specific> - eg src/base/node_24_python_3_14
-These have a .devcontainer/devcontainer.json file used to built the image
-These use the base container as a base and then install specific versions of tools using devcontainer features, or a customised Dockerfile
-If there are specific vulnerabilities from these tools, then these should be added to the .trivyignore file in the folder
+Images under languages should point to a dockerfile under src/common that is based off the base image. This also runs `.devcontainer/scripts/root_install.sh` and `.devcontainer/scripts/vscode_install.sh` as vscode user as part of the build
 
-# Build process
+We use trivy to scan for vulnerabilities in the built docker images. Known vulnerabilities in the base image are in `src/common/.trivyignore.yaml`. Vulnerabilities in specific images are in `.trivyignore.yaml` file in each images folder. These are combined before running a scan to exclude know vulnerabilities
+
+# Pull requests and merge to main process
+For each pull request, and merge to main, images are built and scanned using trivy, but the images are not pushed to github container registry
 Docker images are built for each pull request, and on merges to main.   
 Docker images are built for amd64 and arm64 architecture, and a combined manifest is created and pushed as part of the build.   
 
-The base image is built first, and then all other images are built
+The base image is built first, and then language images, and finally project images. 
 
 Docker images are scanned for vulnerabilities using trivy as part of a build step, and the build fails if vulnerabilities are found not in .trivyignore file.
 
-For pull requests, an image is pushed with tag `pr-<pull-request-id>-<short commit sha>`
-On merges to main, a new release is created, and images are tagged with `latest` and the version of the release.
+
+# Release workflow
+There is a release workflow that runs weekly at 18:00 on Thursday and on demand.   
+This creates a new release tag, builds all images, and pushes them to github container registry.
+Images are tagged with the release tag, and also with latest
 
 # Local testing
-For local testing, you can run this to build the base image
+## Building images
+You can use these commands to build images
+
+Base image
 ```
 CONTAINER_NAME=base \
   BASE_VERSION=latest \
   BASE_FOLDER=. \
   make build-image
 ``` 
-or this to build a language image
+Language images
 ```
 CONTAINER_NAME=node_24_python_3_12 \
   BASE_VERSION=latest \
   BASE_FOLDER=languages \
   make build-image
 ``` 
-or this to build a project image
+Project images
 ```
 CONTAINER_NAME=fhir_facade_api \
   BASE_VERSION=latest \
   BASE_FOLDER=projects \
   make build-image
 ``` 
 
-to build a local image, and then
+## Scanning images
+You can use these commands to scan images
+Base image
 ```
-CONTAINER_NAME=base BASE_VERSION=latest make scan-image
+CONTAINER_NAME=base \
+  BASE_FOLDER=. \
+  make scan-image
 ```
-to scan for vulnerabilities
-
-# Using the images
-In each eps project, you can put this in the devcontainer Dockerfile. You should not need to add any features. 
+Language images
 ```
-FROM ghcr.io/nhsdigital/eps-devcontainers/node_24_python_3_13:<version>
-
-USER root
-# specify DOCKER_GID to force container docker group id to match host
-RUN if [ -n "${DOCKER_GID}" ]; then \
-      if ! getent group docker; then \
-        groupadd -g ${DOCKER_GID} docker; \
-      else \
-        groupmod -g ${DOCKER_GID} docker; \
-      fi && \
-      usermod -aG docker vscode; \
-    fi
-
-USER vscode
+CONTAINER_NAME=node_24_python_3_12 \
+  BASE_FOLDER=languages \
+  make scan-image
+``` 
+Project images
 ```
+CONTAINER_NAME=fhir_facade_api \
+  BASE_FOLDER=projects \
+  make scan-image
+``` 
 
-# Generating a .trivyignore file
-You can generate a .trivyignore file for known vulnerabilities by either downloading the json scan output generated by the build, or by generating it locally using
+## Interactive shell on image
+You can use this to start an interactive shell on built images
+base image
+```
+CONTAINER_NAME=base \
+  make shell-image
+```
+Language images
 ```
-CONTAINER_NAME=base BASE_VERSION=latest make scan-image-json 
+CONTAINER_NAME=node_24_python_3_12 \
+  make shell-image
+``` 
+Project images
 ```
+CONTAINER_NAME=fhir_facade_api \
+  make shell-image
+``` 
+
+
+## Generating a .trivyignore file
+You can generate a .trivyignore file for known vulnerabilities by either downloading the json scan output generated by the build, or by generating it locally using the scanning images commands above with a make target of scan-image-json
+
 If generated locally, then the output goes into .out/scan.out.json
 
-Once you have this, use the following to generate a .trivyignore
+Once you have the scan output, use the following to generate a .trivyignore
 ```
-poetry run python scripts/trivy_to_trivyignore.py --input .out/scan.out.json --output src/common/.trivyignore.yaml 
+poetry run python \
+  scripts/trivy_to_trivyignore.py \
+  --input .out/scan.out.json \
+  --output src/common/.trivyignore.yaml 
 ```