# 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.

{% stepper %}
{% step %}

### Prepare and build your base image

Example initial Dockerfile with your build dependencies:

{% code title="Dockerfile (base)" %}

```dockerfile
FROM ubuntu:22.04

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

{% endcode %}

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

{% code title="Terminal" %}

```bash
docker build -t mybuildimage:latest .
```

{% endcode %}
{% endstep %}

{% step %}

### 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:

{% code title="Dockerfile (with below-orchestrator)" %}

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

{% endcode %}

Build and tag the new image:

{% code title="Terminal" %}

```bash
docker build -t mybuildimage-below:latest .
```

{% endcode %}

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.
  {% endstep %}
  {% endstepper %}

## 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:

{% code title="platforms-docker.yaml" %}

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

{% endcode %}

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`.

{% tabs %}
{% tab title="Linux" %}
Open or create:

{% code title="${HOME}/.config/wedolow/config.json" %}

```
```

{% endcode %}

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

Replace `/path/to/platforms-docker.yaml` with the correct path on your system.
{% endtab %}

{% tab title="Windows" %}
Open or create:

{% code title="C:\Users\<YourUser>\AppData\Roaming\wedolow\config.json" %}

```
```

{% endcode %}

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

Replace `C:\\path\\to\\platforms-docker.yaml` with the correct path on your system.
{% endtab %}
{% endtabs %}

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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.wedolow.com/documentation/ressources/compatibility-guide/custom-docker-image.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.