This repo defines a base Docker image to use for testing Request Tracker
(RT) and its dependencies. It:
* installs required C libraries and build tools from a distribution
* builds Perl from source and runs its tests
* installs cpm and uses it to install most of RT's dependencies, and run their tests
After you build this image, you can use it to:
* run the test suite for RT and its extensions (the Dockerfile and
GitHub Actions in the RT repository provides examples of this)
* deploy the stack of dependencies to other hosts running the same
distribution and architecture, to save build time while maintaining
confidence that it has all passed testing
To help you tailor the image to versions of Perl and RT you're targeting,
and any future deployments you plan to do from that, you can pass build
arguments to control what is built inside of it. The available arguments
are:
* CPANFILE: The URL to RT's cpanfile. The Dockerfile runs cpm to install
most of the modules named in this file, with some additional parsing to
select most optional features. The default is to use the cpanfile from the
current stable RT release available on GitHub. You can use a different URL
to use the cpanfile from a different RT version (e.g., replace `stable` in
the default URL with a different tag name).
* CPM: The URL to the single-file script download published by cpm. You
should only need to set this if cpm moves or if you can't access GitHub.
* PERL_VERSION: The version of Perl that is built, tested, and installed in
the image, written in the same format used in the source releases, like
`5.34.0`. The default is a release that was recently stable last time we
updated the Dockerfile.
* PERL_CONFIGURE: A string of options passed the Perl's configure script
during the build process. The default is `-des`, which gets you a default
build without any interaction. You could change this to set specific
defines, turn on experimental features, etc.
Don't specify `-Dprefix` here. For that, use:
* PERL_PREFIX: The full path where Perl will be installed inside the
container. Default is `/opt/perl-$PERL_VERSION`. You could change this is
if you wanted to use a different path for deployments out of the image.
For routine builds, the only argument you're expected to set is
PERL_VERSION, which you should set to a recent release.
If you specifically want to test older or development versions of Perl
and/or RT, you can do that by setting PERL_VERSION and CPANFILE,
respectively. Testing development versions of Perl may require setting
PERL_CONFIGURE as well.
Because it is oriented towards testing and broader deployment, this Docker
image contains a relatively "maximal" set of dependencies. It installs all
of the modules required to support RT's tests, development features, and
most of its databases and optional features. If you wanted to run RT in
Docker in production, you would probably prefer to be more selective about
what you install, and build a slimmer image.
When you run this container, by default it prints a list all the Perl
modules it contains, along with their versions, in the CPAN "autobundle"
format. This is primarily intended to provide an easy way to compare the
main differences in built images over time. You could also use it to deploy
the exact same set of modules on a different distribution or architecture if
needed.
Building and publishing the image
==================================
Images must be linux/amd64 to run in RT's CI: the runners are amd64, and this
image bundles amd64-only Oracle Instant Client and geckodriver binaries. The
primary way to build and publish is the GitHub Actions workflow in this repo,
which runs on native amd64 runners, so the architecture is always correct no
matter what kind of computer you build from.
When to build
There are two reasons to build a new image:
* To refresh dependencies. Each build pulls the latest available Debian
packages and the latest CPAN module versions, and rebuilds and re-tests the
Perl version you specify. So running the workflow with no source change
produces an up-to-date snapshot of the dependency stack that has passed its
tests. Do this periodically, or to check whether newer module versions still
pass.
* To make a change. Anything structural -- adding a system package or Perl
module, working around a new test failure, pinning or skipping a module, or
moving to a new Debian release -- means editing the Dockerfile first. A few
changes need no file edit and can be set from the workflow inputs instead: a
different Perl version, cpanfile URL, or distro codename.
Either way you get a new, date-stamped tag; nothing is overwritten.
Publishing a new image (primary path)
If your change requires editing the Dockerfile, commit and push it first: the
workflow builds the committed repository, not your local files. You can push
to a branch and run the workflow from that branch to test before merging to
main. A dependency-refresh build needs no edit -- skip straight to step 1.
1. In GitHub, open the "Actions" tab, select the "Build and push base image"
workflow, and click "Run workflow".
2. Fill in the inputs:
rt_version representative RT version for the tag, e.g. 6.0.3
distro Debian codename, e.g. bullseye
perl_version Perl version to build (default 5.34.3)
cpanfile optional cpanfile URL override (blank = Dockerfile default)
use_cache leave unchecked for a standard build (runs all tests);
check only for faster debugging re-runs
The image is tagged
bpssysadmin/rt-base-debian:RT-<rt_version>-<distro>-<YYYYMMDD>.
3. Watch the run in the Actions tab (or "gh run watch" from the CLI). The
final steps verify the pushed image is linux/amd64 and print the tag.
Making the image live in RT's CI
Publishing the image does nothing on its own. To use it, bump the pinned tag
in RT's own Dockerfile:
FROM bpssysadmin/rt-base-debian:RT-<rt_version>-<distro>-<YYYYMMDD>
RT's CI then builds RT on top of the new base image.
Building locally (fallback)
To reproduce a single build failure without waiting on CI, build locally. You
MUST target linux/amd64 and push in one step; a separate "docker push" can
publish a stale, wrong-architecture image:
docker buildx build --platform linux/amd64 --push \
-t bpssysadmin/rt-base-debian:<tag> .
docker buildx imagetools inspect bpssysadmin/rt-base-debian:<tag>
The second command should report linux/amd64. On Apple Silicon this build runs
under QEMU emulation.
One-time setup (admins)
The workflow authenticates to Docker Hub with a Docker Hub access token
(Read/Write) stored as Actions secrets DOCKERHUB_USERNAME and DOCKERHUB_TOKEN,
ideally at the bestpractical organization level. Teammates only need write
access to this repo to run the workflow; no credentials are needed on their
own machines.
https://docs.docker.com/docker-hub/repos/create/