Understanding Build Arguments of the IBM Storage Scale bridge for Grafana Dockerfile - IBM/ibm-spectrum-scale-bridge-for-grafana GitHub Wiki

This guide explains how to use the three build arguments BUILD_ENV, BASE, and PY_VER to:

• select the build stage (prod, test, or custom)
• override the default base image
• choose which Python version is installed inside the container
• recompile open-source Python package dependencies against a specific Python version (via the test stage)

Note: All three arguments are independent and can be combined freely. For custom builds, the Python version is determined solely by the BASE image — PY_VER is not used.

The Dockerfile uses the BASE and PY_VER build arguments to drive Python installation. Behaviour differs per stage:

• Docker 20.10 or later
• Access to registry.access.redhat.com (prod / test) or the Python UBI9 image registry (custom)
• The repository checked out locally

No extra arguments are required. PY_VER defaults to 3.12.

docker build \
  -t grafana-bridge:prod .

Pass --build-arg PY_VER=<version> to install a different Python release. The version must be available as a python<version> package in the UBI9 DNF repository (e.g. 3.9, 3.11, 3.12).

# Python 3.11
docker build \
  --build-arg PY_VER=3.11 \
  -t grafana-bridge:prod-py311 .

# Python 3.9
docker build \
  --build-arg PY_VER=3.9 \
  -t grafana-bridge:prod-py39 .

What happens internally when PY_VER=3.11 is passed:

dnf install -y python3.11 python3.11-pip
python3.11 -m pip install -r requirements_ubi9.txt
ln -sf $(which python3.11) /usr/bin/python3   # sets the default interpreter

By default BASE points to registry.access.redhat.com/ubi9/ubi:9.8-1782365825. Pass --build-arg BASE=<image> to use a different UBI9 image, for example to pin a newer patch release:

docker build \
  --build-arg BASE=registry.access.redhat.com/ubi9/ubi:9.9-1234567890 \
  --build-arg PY_VER=3.12 \
  -t grafana-bridge:prod-ubi99 .

The test stage is used to recompile open-source Python package dependencies from scratch against a specific Python version. Instead of using the pre-pinned requirements_ubi9.txt, it starts from the unpinned requirements_ubi.in and runs pip-tools to resolve and lock all transitive dependencies for the chosen Python version. This is the recommended approach when upgrading Python or refreshing dependency versions.

What happens internally:

pip-compile requirements_ubi.in --output-file requirements_ubi9.txt
python<VER> -m pip install -r requirements_ubi9.txt

docker build \
  --build-arg BUILD_ENV=test \
  -t grafana-bridge:test .

Pass --build-arg PY_VER=<version> to resolve and install packages against a different Python release. The resolved requirements_ubi9.txt is printed to the build log and can be extracted from the image if needed.

# Recompile for Python 3.11
docker build \
  --build-arg BUILD_ENV=test \
  --build-arg PY_VER=3.11 \
  -t grafana-bridge:test-py311 .

# Recompile for Python 3.9
docker build \
  --build-arg BUILD_ENV=test \
  --build-arg PY_VER=3.9 \
  -t grafana-bridge:test-py39 .

Use --build-arg BASE=<image> to build against a different UBI9 image while still controlling the Python version via PY_VER:

docker build \
  --build-arg BUILD_ENV=test \
  --build-arg BASE=registry.access.redhat.com/ubi9/ubi:9.9-1234567890 \
  --build-arg PY_VER=3.11 \
  -t grafana-bridge:test-ubi99-py311 .

The custom stage is designed for UBI9 Python base images that already ship a specific Python version. There is no DNF install step and PY_VER is not used.

Instead, the build detects the version automatically:

_PY_VER=$(python3 --version 2>&1 | sed 's/Python \([0-9]*\.[0-9]*\).*/\1/')

Choose the Python version by selecting the appropriate base image via BASE:

# Python 3.9
docker build \
  --build-arg BUILD_ENV=custom \
  --build-arg BASE=registry.access.redhat.com/ubi9/python-39:1-1778661867 \
  -t grafana-bridge:custom-py39 .

# Python 3.11
docker build \
  --build-arg BUILD_ENV=custom \
  --build-arg BASE=registry.access.redhat.com/ubi9/python-311:1-1234567890 \
  -t grafana-bridge:custom-py311 .

# Python 3.12
docker build \
  --build-arg BUILD_ENV=custom \
  --build-arg BASE=registry.access.redhat.com/ubi9/python-312:1-1234567890 \
  -t grafana-bridge:custom-py312 .

Tip: Find available Python UBI9 image tags at catalog.redhat.com.

# prod — Python 3.12 (default)
docker build -t grafana-bridge:prod .

# prod — Python 3.9
docker build --build-arg PY_VER=3.9 -t grafana-bridge:prod-py39 .

# test — Python 3.12 (default)
docker build --build-arg BUILD_ENV=test -t grafana-bridge:test .

# test — Python 3.9
docker build --build-arg BUILD_ENV=test --build-arg PY_VER=3.9 -t grafana-bridge:test-py39 .

# custom — Python auto-detected from base image (e.g. 3.9)
docker build \
  --build-arg BUILD_ENV=custom \
  --build-arg BASE=registry.access.redhat.com/ubi9/python-39:1-1778661867 \
  -t grafana-bridge:custom-py39 .

After a successful build, confirm the active interpreter inside the image:

docker run --rm grafana-bridge:<tag> python3 --version

Expected output example:

Python 3.9.18