Container

Source Code

First, you'll need to clone the ZMK source repository if you haven't already. Open a terminal and navigate to the folder you would like to place your zmk directory in, then run the following command:

git clone https://github.com/zmkfirmware/zmk.git

Installing Development Tools

VS Code

note

This approach is documented for VS Code not Code OSS.

1. Install Docker Desktop for your operating system.
2. Install VS Code.
3. Install the Remote - Containers extension.

Dev Container CLI

1. Install Docker Desktop for your operating system.
2. Install the Dev Container CLI.

Podman

1. Install Podman for your operating system:
   • Podman CLI
   • Podman Desktop

warning

Please follow the installation instructions carefully. If you do not have a working Podman machine, executing the commands below won't be possible.

Creating Volumes

To build from a zmk-config or with additional modules, it is necessary to first make them available by creating volumes.

Docker

When setting up the container, either using VS Code or the Dev Container CLI, the volumes will automatically be mounted.

Zmk-Config

docker volume create --driver local -o o=bind -o type=none \
  -o device="/absolute/path/to/zmk-config/" zmk-config

Modules

docker volume create --driver local -o o=bind -o type=none \
  -o device="/absolute/path/to/zmk-modules/parent/" zmk-modules

Podman

Zmk-Config

podman volume create --driver local -o o=bind -o type=none \
 -o device="/absolute/path/to/zmk-config/" zmk-config

Modules

podman volume create --driver local -o o=bind -o type=none \
  -o device="/absolute/path/to/zmk-modules/parent/" zmk-modules

Once this is done, you can refer to the zmk-config with /workspaces/zmk-config and /workspaces/zmk-modules to the modules instead of using their full path like it is shown in the build commands, since these are the locations they were mounted to in the container.

note

When changing the configuration or modules directory, new volumes have to be created and mounted. Accordingly, you first have to remove the old ones.

Docker

docker ps                    # List containers
docker stop "<container-id>" # Stop the container
docker rm   "<container-id>" # Remove the container

docker volume ls                 # List volumes
docker volume rm "<volume-name>" # Remove volume

Podman

podman ps                    # List containers
podman stop "<container-id>" # Stop the container
podman rm   "<container-id>" # Remove the container

podman volume ls                 # List volumes
podman volume rm "<volume-name>" # Remove volume

Initialize Container

VS Code

Open the zmk checkout directory in VS Code. The repository includes a configuration for containerized development. Therefore, an alert will pop up:

Click Reopen in Container to reopen the VS Code with the running container. If the alert fails to pop up or you accidentally close it, you can perform the same action by pressing the following keys based on your operating system and selecting Remote: Show Remote Menu:

• Windows/Linux: Ctrl + Shift + P
• MacOs: Cmd + Shift + P

The first time you do this on your machine, it will pull down the Docker image from the registry and build the container. Subsequent launches are much faster!

Dev Container CLI

First, make sure that the Dev Container CLI is installed by running:

devcontainer --version

To be able to start the Dev Container, the Dev Container CLI has to know where the devcontainer.json is located. This can be done using the --workspace-folder option:

devcontainer up --workspace-folder "/absolute/path/to/zmk"

The first time you do this on your machine, it will pull down the Docker image from the registry and build the container. Subsequent launches are much faster!

Once the container is running, you can connect to it by using its container ID. This allows you to execute commands inside the container:

docker ps                                                   # List containers
docker exec -w /workspaces/zmk -it <container_id> /bin/bash # Connect

Podman

First, make sure that Podman is installed by running:

podman --version

Since Podman is largely compatible with Docker, it is possible to use the Dockerfile provided for use with Dev Containers for building a container image.

podman build -t <container-name> -f Dockerfile </path/to/.devcontainer>

Once this is done, the container can be started with the podman run command. Depending on which volumes you are using, you might have to remove mounting options.

podman run -it --rm \
  --security-opt label=disable \
  --workdir /workspaces/zmk \
  -v /path/to/zmk:/workspaces/zmk \
  -v /path/to/zmk-config:/workspaces/zmk-config \   # Removeable
  -v /path/to/zmk-modules:/workspaces/zmk-modules \ # Removeable
  -p 3000:3000 \
  <container-name> /bin/bash

Configure Zephyr Workspace

caution

The following step and any future build commands must be executed from the command line inside the container.

west init -l app/ # Initialization
west update       # Update modules

If you are using a Docker-based approach, you have to restart the container at this point. Stopping it is possible with these commands.

docker ps                    # List containers
docker stop "<container-id>" # Stop the container