Skip to content

Latest commit

 

History

History
111 lines (76 loc) · 3.85 KB

HACKING.adoc

File metadata and controls

111 lines (76 loc) · 3.85 KB
Raw

Hacking documentation

This document explains how to develop on this repository.

Requirements

  • A Bourne-Again-Shell compatible prompt (bash)

  • GNU make 3.80+

  • Docker with BuildX capability

    • Docker 20.10+ is recommended as it is usually packaged with Buildx

    • Docker 19.03+ is required

    • BuildX v0.5.1+ is needed (manual installation of the plugin can be done if you don’t have it: https://github.com/docker/buildx)

  • git 1.6+ (git 2+ is recommended)

  • jq 1.6+

  • curl 7+

We recommend GNU Parallel for parallel test execution, but it is not required.

Tests currently do not work on Mac M1 due to a known issue in 'Docker Desktop 3.4.0'.

Building

Linux

## build all linux platforms
make build

## only build a specific linux image
make build-debian_jdk17 # or build-alpine_jdk17 build-debian_slim_jdk17 build-debian_jdk17 ...

Testing

Linux

Tests for Linux images are written using bats under the tests/ directory.

Tests pre-requisites are automatically managed by the make prepare-test target (dependency of any make test* target) which:

  • Ensures that the bats command is installed in the bats/bin/ directory (along with all the bats project in ./bats/)

  • Ensures that the additional bats helper are installed as git sub-modules in ./tests/test_helper/

For efficiency, the tests are executed in parallel.

Important
 Due to the parallel execution, each test should be self-contained and not depend on another test, even inside a given test harness.

Please note that:

  • You can disable the parallel execution by setting the environment variable DISABLE_PARALLEL_TESTS to the value true

  • Parallel execution is disabled if the commands docker or (GNU) parallel are not installed.

You can restrict the execution to only a subset of test harness files. By setting the environment variable TEST_SUITES to the path of the bats test harness file to execute alone.

## Run tests for all linux platforms
make test

## Run tests for a specific linux platform
make test-debian_jdk17 # or test-alpine_jdk17 test-debian_slim_jdk17 test-debian_jdk17 ...

## Run tests for Alpine Linux JDK17 platform in sequential mode
DISABLE_PARALLEL_TESTS=true make test-alpine_jdk17

## Only run the test suite `functions.bats` for the Debian JDK21 platform
TEST_SUITES=./tests/functions.bats make test-debian_jdk21

Multiarch support

The buildx tool is used to build our multiarch images, this relies on either QEMU for emulating the architecture being built, or a remote builder configured for the required platform(s).

Planned supported architectures:

  • amd64

  • arm64

  • s390x

Debugging

In order to debug the controller, use the -e DEBUG=true -p 5005:5005 when starting the container. Jenkins will be suspended on the startup in such case, and then it will be possible to attach a debugger from IDE to it.

Test the publishing using an overridden target repository on Docker Hub

Create a new dedicated target repository in your Docker Hub account, and use it like follows:

export DOCKERHUB_ORGANISATION=batmat
export DOCKERHUB_REPO=test-jenkins
# The log below will help confirm this override was taken in account:
./publish.sh
Docker repository in Use:
* JENKINS_REPO: batmat/test-jenkins
...