This page details the requirements for configuring and deploying Registry prebuilt container images distributed by the COmanage Project.

1. Preliminaries

Before instantiating a Registry prebuilt image as a container please review the prerequisites below, and then continue with the section on Configuration for details on how to satisfy the prerequisites. 

1.1. Database 

COmanage Registry requires a relational database to store your registry data. Registry is tested against PostgreSQL, MySQL, and MariaDB. It may work against other databases supported by CakePHP, but no other databases are regularly tested. Unless otherwise noted, any currently supported version of these databases may be used.

You do not have to deploy your relational database using a container. The only requirement is that the database server is reachable over the network using TCP (as opposed to a UNIX socket connection). If you do wish to deploy your relational database using a container and orchestrate its deployment with the Registry container, click here for examples. 

Create a new logical database for  Registry. You can name the new database whatever you like since you may configure the container with the name of the database using an environment variable. The default name for the database used by the container is "registry".

1.2. Email

Registry can use email to deliver invitations for enrollment and for notifications. Most container deployments configure Registry to connect to an SMTP server using a password to send email. The SMTP server URL, account name, password, port, sending address, and sending name may be configured for the container using environment variables. Authentication with the SMTP server is not required by the container in case your organization allows connections from trusted networks.

1.3. Authentication

Different container images are available for different authentication mechanisms including Apache HTTP basic authentication, SAML using the Shibboleth Service Provider (SP), and OIDC using the mod_auth_openidc Apache module. The details required to configure each authentication mechanism are different:

1.3.1. SAML using the Shibboleth SP 

Configuring the container requires the following:

  • A SAML entityID for the SP. If your SP will be published in a SAML federation please consult with the federation operator on choosing an appropriate SAML entityID.
  • X.509 certificate for decrypting encrypted SAML assertions sent by a SAML identity provider (IdP) and the corresponding private key. These files are often named sp-encrypt-cert.pem and sp-encrypt-key.pem but those names are not required. If you do not already have a SAML decryption certificate click here for instructions on creating one.
  • X.509 certificate for signing SAML authentication requests sent by the SP to the IdP and the corresponding private key. These files are often named sp-signing-cert.pem and sp-signing-key.pem but those names are not required. If you do not already have a SAML signing certificate click here for instructions on creating one.
  • A source of SAML metadata for federating the SP with IdP(s). If your SP will be published in a SAML federation please consult with the federation operator for how to obtain the federation SAML metadata.

Additional possible configurations include:

  • A SAML IdP discovery service (DS) URL if the SP federates with more than one IdP.

The detailed configuration of the Shibboleth SP is out of scope here. Please see the Shibboleth SP documentation for details on all possible configuration options for the Shibboleth SP.

1.3.2. OIDC using mod_auth_openidc

Configuring the container requires the following:

  • The "well-known" URL for the OIDC Provider (OP) to facilitate OpenID Connect Discovery. This URL has the form "https://server.com/.well-known/openid-configuration".
  • An OIDC client ID and the corresponding client secret.
  • The OIDC scope(s) your client will request.

When obtaining an OIDC client and secret you may be required to register the OIDC callback URI for your deployment. The Registry container image callback URI has the form "https://${COMANAGE_REGISTRY_VIRTUAL_HOST_FQDN}/secure/redirect".

1.3.3. Apache HTTP basic authentication

Configuring the container requires the following:

  • A text file containing the list of users and passwords for authentication. This text file is usually created and managed using the htpasswd utility.

1.4. HTTPS

The Apache HTTP Server (Apache) process running in the container by default listens on both port 80 (HTTP) and port 443 (HTTPS). Incoming requests on port 80 (HTTP) are redirected to port 443 (HTTPS). The listening ports and whether or not both HTTP and HTTPS are served is configured using environment variables.

By default Apache uses a self-signed X.509 certificate for HTTPS. Most deployers will want to inject an X.509 certificate in PEM format (including any intermediate CA signing certificates) and associated private key for Apache to use for HTTPS on port 443.

2. Configuration

Configuring the Registry prebuilt container images involves a combination of setting environment variables and overlaying configuration files, either by using the "slash Root" mechanism, bind mounting the configuration files, or by using the prebuilt image as a base when building a new image and COPYing in the configuration file. Click here for details on configuring the Registry prebuilt container images and for links to sample configurations.


  • No labels