containerbase base

This repository is the source for the Docker images containerbase/base and ghcr.io/containerbase/base. The commits to the main branch are automatically built and published.

Local development

Install a recent version of:

• Docker
• the buildx plugin

Node.js and pnpm are pinned in mise.toml, so mise users can install them with:

> mise install

You must first build the CLI, before you build the Docker images.

> pnpm install
> pnpm build

Base image

If you make changes to the src folder or the Dockerfile, you must:

1. run pnpm build
2. rebuild the containerbase/base image

pnpm build
docker buildx bake

You can use the following command to ignore the remote cache for local testing. This may speed up your local builds.

docker buildx bake  --set *.cache-from=

Test images

To run one of the tests use the following command, it will run the Java tests from test/java.

TAG=java docker buildx bake test

For other test images see the test folder.

pnpm test:docker

Instead of calling docker buildx bake directly, you can use the test:docker script, which wraps the bake calls.

# run all tests from the `test` folder
pnpm test:docker

# rebuild the CLI and run the x86_64 test from `test/java`
pnpm test:docker -b -t test-x86_64 java

# run multiple tests with debug logging
pnpm test:docker -D java node

Any positional argument is the name of a folder in test which contains a Dockerfile. If no test is given, all tests from the test folder are run. Unknown test names are only reported as an error when they are passed explicitly.

The following options are supported:

Option	Description
-b, --build	Run pnpm build to compile the CLI sources before building the images.
-t, --target <name>	The bake target or group to build, defaults to default. Use e.g. test, test-x86_64, test-aarch64 or test-distro.
-d, --dry-run	Reserved for a dry run, currently without effect.
-D, --debug	Set CONTAINERBASE_DEBUG=1 and use plain buildkit progress output.
-l, --log-level <level>	Set CONTAINERBASE_LOG_LEVEL and use plain buildkit progress output.
-p, --plain	Use plain buildkit progress output.
--network <mode>	Docker network mode used for the build, allowed values are default, host and none.
--allow-host-network	Pass --allow=network.host to docker buildx bake, required to use --network host.
--host-gateway <value>	Value used for the host.docker.internal host alias, defaults to host-gateway.

To build against a service running on your host or when having DNS issues from a VPN, use the host network:

pnpm test:docker --network host --allow-host-network -t test-x86_64 java

Distro test images

Jammy

Ubuntu jammy is deprecated and will be removed in the next major release. You can still run the tests with the following command, it will run the test from test/Dockerfile.distro.

TAG=jammy docker buildx bake test-distro

Noble

To run the noble tests use the following command, it will run the test from test/Dockerfile.distro.

TAG=noble docker buildx bake test-distro

Resolute

To run the resolute tests use the following command, it will run the test from test/Dockerfile.distro.

TAG=resolute docker buildx bake test-distro

Adding a new tool

To add support for a new tool read the new-tool docs.

Apt proxy

You can configure an apt proxy for the build by setting an APT_HTTP_PROXY argument. For example: docker build --build-arg APT_HTTP_PROXY=https://apt.company.com . -t my/image

You can export APT_HTTP_PROXY to your local env and our build tools will use your apt proxy for the http sources.

Custom base image

To use a custom base image with containerbase/base read the custom-base-image docs.

Custom Root CA Certificates

To add custom root certificates to the containerbase/base base image read the custom-root-ca docs.

Temporary disable tool installer

To temporarily disable or skip some tool installer: set the build arg IGNORED_TOOLS to a comma separated case-insensitive tool names list.

For example, the following Dockerfile skips the installation of powershell and node:

FROM containerbase/base

ARG IGNORED_TOOLS=powershell,node


# renovate: datasource=github-releases packageName=PowerShell/PowerShell
RUN install-tool powershell v7.1.3

# renovate: datasource=github-releases packageName=containerbase/node-prebuild versioning=node
RUN install-tool node 20.9.0

# renovate: datasource=github-releases packageName=moby/moby
RUN install-tool docker 20.10.7

Custom registries

You can replace the default registries used to download the tools. Read the custom-registries docs for more details.

Logging

The new CLI has some new logging features. You can change the default info log level by setting the CONTAINERBASE_LOG_LEVEL¹ environment variable. If CONTAINERBASE_DEBUG is set to true the CLI will automatically set the log level to debug, if not explicit set.

You can also log to a .ndjson file via CONTAINERBASE_LOG_FILE and CONTAINERBASE_LOG_FILE_LEVEL environment variables. The default value for CONTAINERBASE_LOG_FILE_LEVEL is debug.

Footnotes

1. https://getpino.io/#/docs/api?id=level-string ↩