modularmx/zephyros repository overview

⁠Quick Reference

• Maintained by Modular MX⁠

⁠Supported tags

• 1.3, latest
  • Ubuntu 24.04, Zephyr CI Base Image 0.29.2, Zephyr SDK 1.0.1, Tested with Zephyr 4.4.0
• 1.2.1
  • Same as 1.2 plus tools for document generation
• 1.2
  • Ubuntu 24.04, Zephyr CI Base Image 0.28.7, Zephyr SDK 0.17.4, Tested with Zephyr 4.3.0
• 1.1
  • Ubuntu 24.04, Zephyr CI Base Image 0.28.4, Zephyr SDK 0.17.4, Tested with Zephyr 4.2.0
• 1.0
  • Ubuntu 22.04, Zephyr CI Base Image 0.27.1, Zephyr SDK 0.17.0, Tested with Zephyr 4.1.0

⁠What is this image?

It is not actually the Zephyr OS itself, but rather a container image that provides a development environment for building Zephyr-based projects. It is based on the Zephyr Project CI Base Image, and the tags correspond to its version releases—not to Zephyr release versions. The image includes west and a minimal version of the Zephyr SDK.

It does not include flashing or debugging tools such as OpenOCD or J-Link; these tasks should be run in a separate container. This approach offers flexibility, allowing users to choose whichever tools they prefer.

⁠How to use this image

Run the container with a shared folder using the --mount flag; this will serve as your Zephyr workspace. The container starts with the non root user named user with id of 1000, it is done like this to avoid permission conflicts in you project directory.

docker run -it --rm -w /home/user/workspace --mount type=bind,src="$(pwd)",dst=/home/user/workspace modularmx/zephyros:latest

Once the container is running you can run the west tool to build your projects.

west init
west update

Or create a new projet using our manifest template file. It only comes with a basic structure for the Nordic nRF54L15-DK and JLink, but you can easyly modiy to work witba difernt part number.

west init -m https://github.com/ModularMX/zephyr-template.git
west update

We preapre a series of posts to start with zephyr projects using this same image in our official embedded house web site, you can check it out here⁠

⁠Using compose

You can also check our nice tutorial How to run images with compose⁠⁠

services:
  zephyr:           # container name
    image: modularmx/zephyros:latest
    working_dir: /home/user/workspace
    volumes:        # volume mapping
      - type: bind
        source: ./
        target: /home/user/workspace
    command:        # keep the container running
      sleep infinity

⁠Using a devcontainer

In case you like to use devcontianer⁠ in VSCode or some other IDE with docker support, you can use the following configuration:

{
    // Name of the dev container
    "name": "zephyr-dev", 
    // Docker image     
    "image": "modularmx/zephyros:latest",
    // indicate the working directory inside the container
    "workspaceFolder": "/home/user/workspace",
    
    // set some usefull vs code configuration only existing in our container
    "customizations": {
        "vscode": {
            // Add some extensions
            "extensions": [
                "ms-vscode.cpptools",
                "trond-snekvik.gnu-mapfiles",
                "twxs.cmake"
            ],
            // Set some settings
            "settings": {
                "workbench.colorTheme": "Monokai"
            }
        }
    }
}

⁠Important notes to keep in mind

This is important in case you want to use the image as base for your own

• The toolchain is installed globally at directory /opt/zephyr-sdk
• Default and only user is called user
• This image was tested with the following boards frdm_mcxa156, nRF54L15-dk, stm32h573i-dk and nucleo_g0b1rb
• It is possible your builds fail due to several reasons, some times it is the combination of the SDK and the Zephyr versions, just try to work with the container version is stable for you instead of always use the latest tag.