Devcontainer/docker images for development

• Usage
• Image variants
• Dockerfile nomenclature
  • Folder contents
• Image building
• Development guides
  • Modifying an image
  • Releasing an image
  • Choosing a base image

In this repository are archived many variants of Dockerfiles used internally at Protech Engineering to provide ready-to-go and reproducible build environments.

All images are created using VSCode devcontainers.

Usage

To use these devcontainers you have to, ONLY THE FIRST TIME:

1. Install docker.
2. Add your user to the docker (usually) group and reboot.
3. Add udev rules for accessing USB devices from a non privileged user (TBD).
4. Install VSCode.
5. Install the "Dev Containers" extension.

To use a devcontainer inside your project you have to:

1. Create a .devcontainer folder at the root of the project.
2. In this folder add a devcontainer.json, with the following content:

   {
   	"image": "ghcr.io/protech-engineering/devcontainers:barearm-14.2.Rel1"
   }

3. Open the command palette (CTRL+SHIFT+P or F1), search and run "Dev Containers: Reopen in Container".

Image variants

Name	Tagging convention	Latest version	Notes
barearm	barearm-[ARM toolchain version]	14.2.Rel1	This image implements basic support for ARM bare metal targets. The latest version contains: ARM GCC 14.2.Rel1 (arm-none-eabi) OpenOCD 0.12.0-6 st-link 1.8.0 pyocd 0.36.0 pyocd packs for ST and nRF python 3.8 and 3.12 STM32CubeProgrammer 2.13.0 (CLI) orbuculum 2.2.0 clangd 20.0.1
barearmgui	barearmgui-[ARM toolchain version]	11.3.Rel1	This image inherits the barearm image. The latest version contains the following additional packages for GUI development: GCC 11.3.0 (x86-64) mingw w64 10-win32 SDL2 + Image module (native + mingw) Emscripten 3.1.5
barearmnordic	barearmnordic-[ARM toolchain version]	9_2019_q4_major	This image inherits the barearm image. The latest version contains the following additional packages for nRF-SDK (old version) development: protobuf 3.19.0 nrfutil 6.1.6 ble-serial
esp	still in beta	NA	This image inherits the ESP32 docker image and adds our default tools and devcontainer settings
zephyr	still in beta	NA	This image inherits the zephyr docker image and adds our default tools and devcontainer settings
hdl	still in beta	NA	This image inherits the hdl-containers/impl image and contains tools for FPGA development with an open source toolchain

Dockerfile nomenclature

For each variant is present a folder with the corresponding name inside the root of the repository.

Folder contents

Each folder contains everything that is necessary to build an image. The structure of each of these folders is of a devcontainer project (i.e. instead of using the prebuilt images, you could place the contents of this folder in your project and achieve the same result)

It normally is:

• A .devcontainer folder, containing:
  • A devcontainer.json file, which defines all the container runtime options
  • A Dockerfile, which defines the image contents
• A assert.sh file, that contains the test library used to check if all the tools are present and working inside the image
• A test.sh file, that contains the test suite and is executed after the image is built by the CI, before pushing it to the public.

Image building

Images are automatically built whenever a new tag is published, and are available from the GitHub Container Registry.

$ docker pull ghcr.io/protech-engineering/devcontainers:[variant]-[version]

A push of the tag [variant]-[version] triggers a build for the [variant] version.

Variant names and versions must not contain any - character (dash), because it is used as a separator between variant and version in the tag name.

Development guides

Modifying an image

In the following text, replace [variant] with the image name that you are modifying (e.g. barearm, esp, zephyr). Remember that each variant is saved inside a folder with the same name.

1. Do the needed modifications on the specific Dockerfile
2. To test the image you can either:

   • Commit and push. The continuous integration will build your image and (if there are no errors) publish your latest modifications to the following image:

      docker pull ghcr.io/protech-engineering/devcontainers:[variant]-test
     

     Note that the image can be used as any other inside a devcontainer.json file. Be careful however, at it will change at any new commit, so IT MUST NOT BE USED FOR PRODUCTION

   • Build locally:

      $ npx @devcontainers/cli build --workspace-folder [variant]

     Now you can start the image with the command:

      $ npx @devcontainers/cli up --remove-existing-container --workspace-folder [variant]

     And execute a command (for example starting a shell to explore the contents):

      $ npx @devcontainers/cli exec --workspace-folder [variant] bash

Releasing an image

At this point you should have:

1. Done all the steps described in Modifying an image
2. Verified that everything is working
3. Used the (test) image in a project for a few weeks, and not found any problems

If everything is done you can release a new stable image:

1. You should make a new commit (it can be --allow-empty) with an explanatory message:

   Modification quick description (Main tooling version)
   
   * Contained tool #1 Version
   * Contained tool #2 Version
   * ....
   

   For an example message see commit 915f50968f28ee61fd94185b5b34c6a176447bc4

2. Create a new tag and push it.

   Choose the tag name very carefully!

   The format is [variant]-[version] where variant is the suffix of the corresponding dockerfile and version should be chosen according to the tagging convention decided and documented here.

   Note that only the - dash separator between variant and version is allowed. If there is more than one the image won't build.

3. Check github actions to see the progress of the automatic building that is triggered by the release creation. If everything went fine the new image is available here:

   $ docker pull ghcr.io/protech-engineering/devcontainers:[variant]-[version]
   

Choosing a base image

• For embedded targeted images: always choose mcr.microsoft.com/devcontainers/base, with the Ubuntu variant. For the version tag, use the semantic versioning, e.g. 1.0.8-jammy or 1.0.8-ubuntu-22.04. When choosing the ubuntu versions you must choose an LTS:

   FROM mcr.microsoft.com/devcontainers/base:1.0.8-ubuntu-22.04

• If another image already exists for your purpose, (it's the case, for example, of zephyr or ESP32 images), it can be adapted to be a devcontainer by adding the following code to its [variant]/.devcontainer/devcontainer.json file:

   "features": {
   	"ghcr.io/devcontainers/features/common-utils:2": {
   		"installZsh": "true",
   		"username": "vscode",
   		"userUid": "1000",
   		"userGid": "1000",
   		"upgradePackages": "true"
   	}
   },

  This will add al the needed packages to make it usable as a devcontainer, even if it's not derived from a devcontainer/base image.