1. Using the Provided Build Script

1.1. Overview

The build script is a bash script provided with the Registry source code that uses docker build to build Registry container images. The build script may be used to build one container that uses a particular authentication technology (e.g. Shibboleth SP, mod_auth_openidc, ...) or to build all container images. This is the same build script used by the project to produce the prebuilt images. Using the build script to create images is not required. You may build images from the source yourself using the provided Dockerfiles.

The build script enforces a convention for image names. See below for a detailed discussion of the image name convention, or the help message for the build script.

The build script may also be used to build container images for tools often deployed with Registry, such as slapd and crond.

Note that build process uses multi-stage builds and during the build process one or more base images will be built and then later used as the base for the deployable container images. The build script does not remove or delete the base images in order to facilitate fast building when a change only affects the deployable image.

1.2. Image Names

The build script builds images with the full name

IMAGE_REGISTRY/REPOSITORY/NAME:TAG

where:

  • NAME is comanage-registry when building Registry. 
  • TAG has the format LABEL-AUTHENTICATION-SUFFIX
    • LABEL is either specified as an argument to the build script, or if not specified LABEL is determined by inspecting the source tree and will have the format GITHUB_TAG or GITHUB_BRANCH-COMMIT.
    • AUTHENTICATION is one of basic-auth, shibboleth-sp-supervisor, mod_auth_openidc, or all
    • SUFFIX is a required argument for the build script
  • REPOSITORY and IMAGE_REGISTRY are used to facilitate pushing the built image to remote repositories. The defaults are empty but can be input using command line arguments to the build script.

1.2.1. Example Image Names

Here are some example image names to illustrate the convention:

  • comanage-registry:4.1.2-shibboleth-sp-supervisor-1
  • comanage-registry:4.1.2-mod_auth_openidc-1
  • comanage-registry:4.1.2-basic-auth-1
  • comanage-registry:develop-53966aef-shibboleth-sp-supervisor-1
  • comanage-registry:hotfix-4.1.x-05bdf0c5-3
  • 999999999999.dkr.ecr.us-east-1.amazonaws.com/comanage/comanage-registry:4.1.2-shibboleth-sp-supervisor-1
  • comanageproject/comanage-registry:4.1.2-shibboleth-sp-supervisor-1
  • quay.io/myorg/comanage-registry:4.1.2-shibboleth-sp-supervisor-1

1.3. Build Script Help Message

Click here for the current build script help message.

1.4. Building An Image

  1.  Clone the Registry source code repository and change directories to the checked out repository:

    git clone https://github.com/Internet2/comanage-registry.git
cd comanage-registry
  2. Choose an authentication method, one of basic-auth, shibboleth-sp-supervisor, mod_auth_openidc, or all.
  3. Choose an image tag suffix. For a given Registry release we recommend starting with 1 and increasing the tag suffix each time a new image is built, for example to pick up any changes or security fixes in other tools like Apache HTTP Server.

  4. Run the build script:

    ./container/build.sh --suffix=SUFFIX registry AUTHENTICATION

    You must run the command from the top directory of the Registry source tree and use the path ./container/build.sh

  5. To build Registry from a different branch or commit (rather than building a tagged release) simply checkout the branch or commit. See the examples below for details.

1.5. Examples

1.5.1. Registry using Shibboleth SP and tag suffix 1

./container/build.sh --suffix=1 registry shibboleth-sp-supervisor


1.5.2. Registry using mod_auth_openidc and tag suffix 1

./container/build.sh --suffix=1 registry mod_auth_openidc

1.5.3. Increasing the suffix tag

If you later rebuild the image using the same version of Registry, for example to pickup security patches in Apache HTTP Server, you would usually just increment the suffix.

./container/build.sh --suffix=2 registry shibboleth-sp-supervisor

1.5.4. Building from the develop branch

git checkout develop
./container/build.sh --suffix=1 registry shibboleth-sp-supervisor

1.5.5. Building from the hotfix-4.1.x branch

git checkout hotfix-4.1.x./container/build.sh --suffix=1 registry mod_auth_openidc

1.5.6. Using a date as the tag suffix

./container/build.sh --suffix=2022_10_07 registry shibboleth-sp-supervisor

This will build the image with name comanage-registry:4.1.2-shibboleth-sp-supervisor-2022_10_07.

1.5.7. Ignoring the build cache

./container/build.sh --suffix=1 --no-cache registry shibboleth-sp-supervisor

1.5.8. Using a custom tag prefix

./container/build.sh --suffix=1 --label=our_special_image registry shibboleth-sp-supervisor

This will build the image with name comanage-registry:our_special_image-shibboleth-sp-supervisor-1.

1.5.9. Building and pushing to a private AWS ECR repository

./container/build.sh --suffix=1 --image_registry=999999999999.dkr.ecr.us-east-1.amazonaws.com registry shibboleth-sp-supervisor
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 999999999999.dkr.ecr.us-east-1.amazonaws.com
docker push 999999999999.dkr.ecr.us-east-1.amazonaws.com/comanage-registry:4.1.2-shibboleth-sp-supervisor-1

2.  Building from a GitHub Pull Request

You can fetch a GitHub pull request based on its ID and create a new local branch that includes the code from the pull request (applied to the branch on which the pull request is based).

  1. Identify the GitHub pull request ID or number that you want to include in your image. For example, this GitHub pull request https://github.com/Internet2/comanage-registry/pull/483 has ID 483.
  2. Decide on a name for your local branch, for example pull_request_483.

  3. Fetch the pull request and create the new local branch with the code:

    git fetch origin pull/ID/head:BRANCH_NAME

  4. Checkout the new local branch you just created. For example

    git checkout pull_request_483

  5. Run the build script with the options for tag name(s) and images you wish to create. For example

    ./container/build.sh -s 1 registry shibboleth-sp-supervisor

    By default the created Registry image name will have the following format:

    comanage-registry:BRANCH_NAME-COMMIT_HASH-AUTHENTICATION-SUFFIX

    An example is

    comanage-registry:pull_request_483-f593245c-shibboleth-sp-supervisor-1

    You can adjust the name of the image by the name you choose for the branch and using the command line arguments for the build script. Click here for the current build script help message.

To build an image that includes two (2) or more pull requests, fetch and create a local branch for each pull request, then create an entirely new local branch and merge each of the local branches with the pull requests into the new branch and build.

3.  Changing the PHP Base Image

The build files by default track the latest minor release of a PHP major version and use the latest image from the Official PHP repository, specifically the "<version>-apache-<Debian version>" tag. You can override the base image to use a different version of PHP (including release candidates) by using the --build-arg flag and the PHP_IMAGE_VERSION argument. For example 

./container/build.sh -s 1 --build-arg PHP_IMAGE_VERSION=8.2.5RC1 registry all

4. Building Using docker build

For full control over the build process and the naming of the images you may build the images directly rather than using the build script. 


The build process uses multi-stage builds. The Registry base image includes Registry source code, utility functions, and scripts common to all images regardless of the authentication method. You MUST build the base image(s) first before building the final deployable image.

  1. Clone the Registry source code repository and change directories to the checked out repository:

    git clone https://github.com/Internet2/comanage-registry.git
cd comanage-registry

  2. If you do not wish to build from the main branch, checkout the branch or commit you wish to build:

    git checkout <branch or commit>

  3. Define the variable COMANAGE_REGISTRY_VERSION:

    export COMANAGE_REGISTRY_VERSION=4.1.2

  4. Define the variable COMANAGE_REGISTRY_BASE_IMAGE_VERSION:

    export COMANAGE_REGISTRY_BASE_IMAGE_VERSION=1

  5. Build the base image:

    docker build \
    --tag comanage-registry-base:${COMANAGE_REGISTRY_VERSION}-${COMANAGE_REGISTRY_BASE_IMAGE_VERSION} \
    --build-arg COMANAGE_REGISTRY_VERSION=${COMANAGE_REGISTRY_VERSION} \
    --file container/registry/base/Dockerfile .

  6. If you are building an image that uses the Shibboleth SP for authentication, you must build a base Shibboleth SP image. If not, you may skip this step:

    export COMANAGE_REGISTRY_SHIBBOLETH_SP_VERSION=3.4.1
export COMANAGE_REGISTRY_SHIBBOLETH_SP_BASE_IMAGE_VERSION=1
docker build \
    --tag comanage-registry-shibboleth-sp-base:${COMANAGE_REGISTRY_SHIBBOLETH_SP_VERSION}-${COMANAGE_REGISTRY_SHIBBOLETH_SP_BASE_IMAGE_VERSION} \
    --build-arg SHIBBOLETH_SP_VERSION=${COMANAGE_REGISTRY_SHIBBOLETH_SP_VERSION} \
    --file container/shibboleth-sp-base/Dockerfile .
  7. Build the deployable image. The build command depends on which authentication method you are using:

    1. Basic Authentication

      docker build \
    --tag TAG \
    --build-arg COMANAGE_REGISTRY_VERSION=${COMANAGE_REGISTRY_VERSION} \
    --build-arg COMANAGE_REGISTRY_BASE_IMAGE_VERSION=${COMANAGE_REGISTRY_BASE_IMAGE_VERSION} \
    --file container/registry/basic-auth/Dockerfile .

    2. Shibboleth SP

      docker build \
    --tag TAG \
    --build-arg COMANAGE_REGISTRY_VERSION=${COMANAGE_REGISTRY_VERSION} \
    --build-arg COMANAGE_REGISTRY_BASE_IMAGE_VERSION=${COMANAGE_REGISTRY_BASE_IMAGE_VERSION} \
    --build-arg COMANAGE_REGISTRY_SHIBBOLETH_SP_VERSION=${COMANAGE_REGISTRY_SHIBBOLETH_SP_VERSION} \
    --build-arg COMANAGE_REGISTRY_SHIBBOLETH_SP_BASE_IMAGE_VERSION=${COMANAGE_REGISTRY_SHIBBOLETH_SP_BASE_IMAGE_VERSION} \
    ---file container/registry/shibboleth-sp-supervisor/Dockerfile .

    3. mod_auth_openidc

      docker build \
    --tag TAG \
    --build-arg COMANAGE_REGISTRY_VERSION=${COMANAGE_REGISTRY_VERSION} \
    --build-arg COMANAGE_REGISTRY_BASE_IMAGE_VERSION=${COMANAGE_REGISTRY_BASE_IMAGE_VERSION} \
    --file container/registry/mod_auth_openidc/Dockerfile .

5. Configuring and Running the Container Images

The details for configuring and running container images that you build yourself are the same as for the prebuilt images from the COmanage Project, though you must adapt the examples to use the image names for the actual images you built.

  • No labels