Custom Docker image

Add beLow dependencies to your build image

For beLow to work, your image must embed below-orchestrator and its dependencies. WedoLow provides installers for multiple Linux distributions (Ubuntu 22.04, Debian 11, RHEL8...).

We will take the example of an Ubuntu 22.04 Docker image for the example unrolled in this section.

1

Prepare and build your base image

Example initial Dockerfile with your build dependencies:

Dockerfile (base)

FROM ubuntu:22.04

# The installation of your own dependencies go here...

Build and tag this Docker image (skip if already built or tagged):

Terminal

docker build -t mybuildimage:latest .

2

Create a Docker image embedding below-orchestrator

In a separate directory, place the below-orchestrator.deb installer provided by WedoLow and create a new Dockerfile like the following:

Dockerfile (with below-orchestrator)

FROM mybuildimage:latest

# Copy Orchestrator installer
COPY below-orchestrator.deb below-orchestrator.deb

# Install Orchestrator
RUN apt-get update && export DEBIAN_FRONTEND=noninteractive && \
    apt-get install -y ./below-orchestrator.deb && \
    rm -rf /var/lib/apt/lists/* && \
    rm below-orchestrator.deb

ENTRYPOINT [ "/usr/local/bin/below-orchestrator" ]

Build and tag the new image:

Terminal

docker build -t mybuildimage-below:latest .

Notes:

• If your original image had an ENTRYPOINT, it will be replaced when using the Docker image in beLow. Call the original entrypoint explicitly in scripts defined in beLow if needed.
• If you push your build image to a Docker registry, also push the beLow build image (mybuildimage-below:latest) to the same registry so it remains available if local images are cleaned.

Declare your build image as a new platform

To use the modified Docker image, beLow must know about it. This requires a beLow runner running in Docker mode. If you manage services with beLowCTL on a local install, you already have a Docker runner. The instructions below show how to configure this using beLowCTL.

Create a YAML file (for example platforms-docker.yaml) containing the platform declaration:

platforms-docker.yaml

- usage: build
  type: docker
  arch: x86_64
  system:
    - name: Linux System
      os:
        - name: "Ubuntu"
          version:
            - name: "22.04 - Custom build environment"
              imageTag: "mybuildimage-below:latest"
              imagePlatform: "linux/amd64"
      cpu:
        - name: "Any"

Replace the arch, system.os.version.imageTag and system.os.version.imagePlatform values as needed. The other fields are primarily for display (except usage and type).

Now declare this platform file in beLowCTL configuration. Open or create the beLow config file and set the runner.docker.platform_file path to the path of platforms-docker.yaml.

Linux

Open or create:

${HOME}/.config/wedolow/config.json

{
  "runner": {
    "docker": {
      "platform_file": "/path/to/platforms-docker.yaml"
    }
  }
}

Replace /path/to/platforms-docker.yaml with the correct path on your system.

Windows

Finally, restart beLowCTL if it is running.

When using beLow, you will now see an additional platform corresponding to your Docker image. Selecting this platform causes scripts to run in containers created from that image.

Important: Do not remove the platforms-docker.yaml file. If it is missing, the Docker runner will error on startup and break beLow. Keep it in a safe place (for example next to the config.json) so it persists while beLow is installed on your system.