mender-client-docker

mender-client-docker enables management of containerized applications on Docker-enabled IoT devices via the Mender client, without additional host requirements.

• mender-client-docker
  • Usage
    • mender-client-docker-launcher usage
      • mender-client-docker-launcher inputs
    • mender-client-docker usage
• Contributing
  • Build the image
  • Test the image
    • devcontainer
      • devcontainer basic usage
      • devcontainer Codespaces usage
      • devcontainer pre-commit usage
    • CI/CD
    • Settings

Usage

The core Mender client functionality is provided by the mender-client-docker image. The mender-client-docker-launcher image offers a convenience layer to manage setup and bringup of a mender-client-docker container on a system, and is the recommended pattern.

The mender-client-docker pattern requires a TENANT_TOKEN variable to authenticate against the Mender host. The mender-client-docker-launcher can optionally pass the TENANT_TOKEN through, or can retrieve a value from the Mender API using a personal access token MENDER_PAT (recommended).

mender-client-docker-launcher usage

Basic usage:

export MENDER_PAT=<Mender personal access token>
docker run \
  --rm \
  --name mender-client-docker-launcher \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e MENDER_PAT \
  -e MAC_ADDRESS=<e.g. $(cat /sys/class/net/eth0/address)> \
  -e DEVICE_TYPE=<your device type> \
  ghcr.io/rcwbr/mender-client-docker-launcher:0.6.2

mender-client-docker-launcher inputs

The following environment variables configure the mender-client-docker-launcher:

Variable	Default	Effect
MAC_ADDRESS	N/A	If provided, this becomes the MAC address associated with the client container, and thus the device as seen on Mender server.
MENDER_HOST	https://hosted.mender.io	The URL of the Mender server instance against which to authenticate.
MENDER_PAT	N/A	If provided, this is the access token used to authenticate to the Mender API and retrieve the tenant token.
TENANT_TOKEN	N/A	If provided, this is the tenant token directly. Precludes the use of MENDER_PAT.

mender-client-docker usage

⚠️ Requires Docker compose on the host system.

Prepare a Docker compose file for the setup and client containers:

services:
  mender-client-setup:
    image: ghcr.io/rcwbr/mender-client-docker:0.6.2
    container_name: mender-client-setup
    environment:
      DEVICE_TYPE: ${DEVICE_TYPE}
      TENANT_TOKEN: ${TENANT_TOKEN}
    entrypoint: /setup-entrypoint
    volumes:
      - mender-client-config:/etc/mender
  mender-client:
    image: ghcr.io/rcwbr/mender-client-docker:0.6.2
    container_name: mender-client
    volumes:
      - mender-client-config:/etc/mender
      - mender-client-data:/var/lib/mender
      - /var/run/docker.sock:/var/run/docker.sock
    restart: always
    depends_on:
      mender-client-setup:
        condition: service_completed_successfully

volumes:
  mender-client-config:
  mender-client-data:

Launch the compose specification:

export TENANT_TOKEN=<Mender org token>
docker compose up -d

Contributing

Build the image

Configure a compatible Docker Buildx builder:

docker builder create --use --bootstrap --driver docker-container

Build the image:

cd docker/mender-client-docker
IMAGE_NAME=mender-client-docker REGISTRY=ghcr.io/rcwbr docker buildx bake -f github-cache-bake.hcl -f cwd://docker-bake.hcl https://github.com/rcwbr/dockerfile-partials.git#0.10.0

Test the image

Start the container:

cd test
export TENANT_TOKEN=<your Mender org token>
./test-launch

To update the test container to a newly build image without reconfiguring using the TENANT_TOKEN:

cd test
./test-updated-image

devcontainer

This repo contains a devcontainer definition in the .devcontainer folder. It leverages the devcontainer cache build tool and layers defined in the dockerfile-partials repo.

devcontainer basic usage

The devcontainer cache build tool requires authentication to the GitHub container registry.

devcontainer Codespaces usage

For use with Codespaces, the *_CONTAINER_REGISTRY_* GHCR access credentials must be stored as Codespaces secrets (see instructions), as must values for USER, and UID (see useradd Codespaces usage).

devcontainer pre-commit usage

By default, the devcontainer configures pre-commit hooks in the repository to ensure commits pass basic testing. This includes enforcing conventional commit messages as the standard for this repository, via commitlint.

CI/CD

This repo uses the release-it-gh-workflow, with the file-bumper image defined as its automation.

It leverages the devcontainer-cache-build workflow to pre-generate devcontainer images, which are also used for the linting enforcement pre-commit workflow.

Settings

The GitHub repo settings for this repo are defined as code using the Probot settings GitHub App. Settings values are defined in the .github/settings.yml file. Enabling automation of settings via this file requires installing the app.

The settings applied are as recommended in the release-it-gh-workflow usage, including tag and branch protections, GitHub App and environment authentication, and required checks.