Simple Plugin Development Sandbox with MariaDB

Follow these steps to build and run a simple deployment of COmanage Registry suitable for beginning COmanage Registry plugin development. This sandbox deployment uses MariaDB for persistent storage and simple basic authentication to COmanage Registry.

Preliminaries

Install Docker. These instructions require version 19.03 or higher.
Install Docker Compose. These instructions require version 1.27.0 or higher.
Clone this repository:

git clone https://github.internet2.edu/docker/comanage-registry-docker.git
cd comanage-registry-docker

Define the shell variable COMANAGE_REGISTRY_VERSION to be the version of COmanage Registry you want to deploy. See the COmanage Registry Release History wiki page for the list of releases. We recommend using the latest release.

Here is an example (but please check the wiki page for the latest release number):

export COMANAGE_REGISTRY_VERSION=4.0.2

Build necessary images

The COmanage Registry images use multi-stage builds.

Build the base COmanage Registry image:

pushd comanage-registry-base
export COMANAGE_REGISTRY_BASE_IMAGE_VERSION=1
TAG="${COMANAGE_REGISTRY_VERSION}-${COMANAGE_REGISTRY_BASE_IMAGE_VERSION}"
docker build \
    --build-arg COMANAGE_REGISTRY_VERSION=${COMANAGE_REGISTRY_VERSION} \
    -t comanage-registry-base:$TAG .
popd

Next use the base image and layer on top Apache HTTP Server Basic Auth (Basic Auth) as the authentication mechanism:

pushd comanage-registry-basic-auth
export COMANAGE_REGISTRY_BASIC_AUTH_IMAGE_VERSION=1
TAG="${COMANAGE_REGISTRY_VERSION}-basic-auth-${COMANAGE_REGISTRY_BASIC_AUTH_IMAGE_VERSION}"
docker build \
    --build-arg COMANAGE_REGISTRY_VERSION=${COMANAGE_REGISTRY_VERSION} \
    --build-arg COMANAGE_REGISTRY_BASE_IMAGE_VERSION=${COMANAGE_REGISTRY_BASE_IMAGE_VERSION} \
    -t comanage-registry:$TAG .
popd

Next layer on top useful development tools:

pushd comanage-registry-basic-auth-develop
export COMANAGE_REGISTRY_BASIC_AUTH_DEVELOP_IMAGE_VERSION=1
TAG="${COMANAGE_REGISTRY_VERSION}-basic-auth-develop-${COMANAGE_REGISTRY_BASIC_AUTH_DEVELOP_IMAGE_VERSION}" 
docker build \
  --build-arg COMANAGE_REGISTRY_VERSION=${COMANAGE_REGISTRY_VERSION} \
  --build-arg COMANAGE_REGISTRY_BASE_IMAGE_VERSION=${COMANAGE_REGISTRY_BASE_IMAGE_VERSION} \
  -t comanage-registry:$TAG .
popd

Deploy the development sandbox

Create a directory somewhere to save the state of the COmanage Registry database. For example

mkdir -p ${HOME}/comanage/var/lib/mysql

Create a directory somewhere for the local COmanage Registry directory. The plugin you develop will reside under the local directory. For example

mkdir -p ${HOME}/comanage/srv/comanage-registry/local

Create a docker-compose.yml file. Below is an example. The details will depend where you create the database state and COmanage Registry local directories.

Be sure to adjust the volume source paths to use the directories you just created.

version: '3.8'

services:

    comanage-registry-database:
        image: mariadb:10.1
        volumes:
            - type: bind
              source: ${HOME}/comanage/var/lib/mysql
              target: /var/lib/mysql
        environment:
            - MYSQL_ROOT_PASSWORD=password
            - MYSQL_DATABASE=registry
            - MYSQL_USER=registry_user
            - MYSQL_PASSWORD=password

    comanage-registry:
        image: "comanage-registry:${COMANAGE_REGISTRY_VERSION}-basic-auth-develop-1"
        volumes:
            - type: bind
              source: ${HOME}/comanage/srv/comanage-registry/local
              target: /srv/comanage-registry/local
        environment:
            - COMANAGE_REGISTRY_DATASOURCE=Database/Mysql
        ports:
            - "80:80"
            - "443:443"

Start the services:

docker-compose -p comanage up -d

Monitor the log files by doing

docker-compose -p comanage logs -f

It will take a few seconds for the database to initialize and for the COmanage Registry container to recognize that the database is ready. The COmange Registry container is ready when you see

[core:notice] [pid 1] AH00094: Command line: 'apache2 -D FOREGROUND'

Login to COmanage Registry with basic authentication

Browse to port 443 on the host, for example https://localhost/. You will have to click through the warning from your browser about the self-signed certificate used for HTTPS.
Click Login and when prompted enter registry.admin as the username and password for the password.
You will be authenticated to COmanage Registry as the first platform administrator (identified by the wrench icon in the left menu).

Plugin development

Develop your plugin in the Plugin directory created by the container in the "local" COmanage Registry directory you created above.
Visit the Writing Registry Plugins wiki page in the COmanage Registry Technical Manual. See also the COmanage Developer Manual, and specifically the wiki page on COmanage Coding Style.
If your plugin adds new tables to the database schema you will need to break into the running COmanage Registry container to run the CakePHP database command. To break into the container and run the database command:

docker exec -it comanage_comanage-registry_1 /bin/bash
cd app
./Console/cake database

When you are finished enter exit to end the bash shell process and exit the container.

Stopping and removing services

To stop the services:

docker-compose -p comanage stop

To restart the services:

docker-compose -p comanage start

To remove the containers and networks (database state will be saved):

docker-compose -p comanage down

Adding more test users

The simple plugin development sandbox uses standard HTTP basic authentication, and in particular the Apache HTTP Server implementation of basic authentication. The default user is registry.admin and the default password is password.

To add more test users begin by copying the default basic authentication file from a running container to your file system, for example

docker cp comanage_comanage-registry_1:/etc/apache2/basic-auth ./basic-auth

Move that file to somewhere on your filesystem where you can use it as another bind-mount volume for the COmanage Registry container, for example

mkdir -p ${HOME}/comanage/etc/apache2/
cp basic-auth ${HOME}/comanage/etc/apache2/basic-auth

Edit the docker-compose file and add the bind-mount for the comanage-registry service, for example

volumes:
    - type: bind
      source: ${HOME}/comanage/srv/comanage-registry/local
      target: /srv/comanage-registry/local
    - type: bind
      source: ${HOME}/comanage/etc/apache2/basic-auth
      target: /etc/apache2/basic-auth

Edit the basic-auth file using the htpasswd command:

htpasswd ${HOME}/comanage/etc/apache2/basic-auth <username>

Restart the services and you can now authenticate to COmanage Registry using the username and password combination you added to the password file.

Note that an authentication module used in production, like the Shibboleth Service Provider (SP), often sets the "username" to a more sophisticated value. For example, if the Shibboleth SP is configured to consume eduPersonPrincipalName (ePPN) and populate that into REMOTE_USER then the "username" might be a value like scott.koranda@illinois.edu.

You can mock up the same behavior by simply adding the "username" scott.koranda@illinois.edu with a password using the above technique.

Mocking Apache CGI environment variables

Some COmanage Registry functionality, such as the Env Source Organizational Identity Source, requires that the Apache HTTP Server set Apache CGI environment variables. These environment variables are usually set by more sophisticated authentication modules like the Shibboleth (SP). You can mock up the same behavior using the SetEnv directive for Apache.

To mock up an environment variable begin by copying the default Apache configuration file from a running container to your file system, for example

docker cp comanage_comanage-registry_1:/etc/apache2/sites-available/000-comanage.conf ./000-comanage.conf