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/