Custom Docker image

Some of your project might be compiled inside Docker containers. For beLow to properly work in such an infrastructure, multiple things must be respected:

• Some tools provided by WedoLow must be installed in the build Docker image

• The new Docker image must be declared as a new build platform.

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.

Let's imagine you have a Dockerfile with your build dependencies:

Initial Dockerfile

FROM ubuntu:22.04

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

First, we'll start by building and tagging this Docker image. If your Docker image is already built or already have an existing tag, skip this step.

In a terminal in the Dockerfile's directory, run:

docker build -t mybuildimage:latest .

Create a new Dockerfile in another directory. In the same directory, add the installer below-orchestrator.deb provided to you by WedoLow.

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" ]

Then, build and tag the new image.

docker build -t mybuildimage-below:latest .

Your image is ready to be used.

If your original image had an entrypoint defined, it will be replaced when using the Docker image in beLow. Therefore, this original entrypoint should be called explicitely in scripts defined in beLow.

If you push your build image to a Docker registry, it is advised to also push the build image for beLow on the same registry, this way it will remain available even if you clean the local Docker images.

Declare your build image as a new platform

Now your modified Docker image is created, beLow must know how to use it. To do that, you must have a beLow runner running in Docker mode. If you are using beLowCTL to manage your services on a local install, you automatically have a Docker runner running. This section shows the configuration when using beLowCTL. Running manually a Docker runner is not documented for now, and this section will show you how to do when using beLowCTL.

First, create a YAML file with the following content, somewhere on your disk, e.g called platforms-docker.yaml:

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 with adapted values if needed, the other fields being used only for display (except for usage and type).

Now we must change beLowCTL configuration file to declare this file. The position of this file and its content changes depending on the OS.

Linux

Open or create the following file:

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

Set the following content to the file:

config.json

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

replacing platform_file value with the right path.

Windows

Open or create the following file:

C:\Users\<YourUser>\AppData\Roaming\wedolow\config.json

Set the following content to the file:

config.json

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

replacing platform_file value with the right path.

Finaly, restart beLowCTL if it is running.

When using beLow, you now see an additional platform corresponding to your Docker image. When using this platform and entering scripts, these scripts will run into containers using this image.

Do not remove platforms-docker.yaml file, this would lead to an error while Docker runner is starting and would break beLow. Keep it in a safe place, e.g. in the same directory as the config.json (it will be persisted as long as beLow in installed on your system).