Skip to content
Permalink
3.3.1-20210213
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

comanage-registry-docker/docs/simple-development.md

Go to file
 
 
Cannot retrieve contributors at this time
Simple Development Sandbox Adding more test users Mocking Apache CGI environment variables Important Notes
245 lines (185 sloc) 7.81 KB
Raw Blame
Open in GitHub Desktop

Simple Development Sandbox

Follow these steps to build and run a simple deployment of COmanage Registry suitable for beginning COmanage Registry development.

  • Complete all of the steps in Evaluating COmanage Registry using Docker. Make sure you can log into COmanage Registry but do not save any changes. Be sure to run docker compose down so that no containers are left running.

  • Create a directory somewhere to save the state of the COmanage Registry database. For example, on Linux

sudo mkdir -p /srv/docker/var/lib/postgresql/data

On Mac OS you might instead do something like

mkdir -p $HOME/comanage-data/postgresql/data
  • Clone the COmanage Registry repository somewhere, for example
cd $HOME
git clone https://github.com/Internet2/comanage-registry.git
  • Change directories into the repository you just cloned and create some necessary files and set appropriate permissions:
cd comanage-registry
cp -a app/tmp.dist local/tmp
chmod -R o+rw local/tmp
  • Tell git to ignore changes the container makes during startup:
git update-index --assume-unchanged app/Config/bootstrap.php
  • Checkout the develop branch or any other branch you want to work from (you probably do not want to work from master):
git checkout develop

  • Edit the docker-compose.yml file you used previously and add three volume bind mounts:

    1. One volume will mount the directory you created in the above step for saving the database state to the directory /var/lib/postgresql/data inside the database container.
    2. A second volume will mount the app directory from the COmanage Registry repository clone you created to the /srv/comanage-registry/app directory inside the COmanage Registry container.
    3. The third volume will mount the local directory from the COmanage Registry repository clone to the /srv/comanage-registry/local directory inside the COmanage Registry container.

Below is an example. The details will depend where you create the database state directory and the repository clone. Be sure to adjust the volume mounts for your deployment.

version: '3.1'

services:

    comanage-registry-database:
        image: comanage-registry-postgres
        volumes:
            - /srv/docker/var/lib/postgresql/data:/var/lib/postgresql/data

    comanage-registry:
        image: "comanage-registry:${COMANAGE_REGISTRY_VERSION}-basic-auth"
        volumes:
            - /home/skoranda/comanage-registry/app:/srv/comanage-registry/app
            - /home/skoranda/comanage-registry/local:/srv/comanage-registry/local

        ports:
            - "80:80"
            - "443:443"

docker-compose up -d

  • 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.

  • Visit the COmanage Developer Manual for tips and suggestions as well as the COmanage Coding Style.

  • To stop the services:

docker-compose stop
  • To remove the containers and networks:
docker-compose down

Adding more test users

The simple 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-registry:/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 /srv/docker/etc/apache2/
cp basic-auth /srv/docker/etc/apache2/basic-auth

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

volume:
    - /srv/docker/etc/apache2/basic-auth:/etc/apache2/basic-auth

Edit the basic-auth file using the htpasswd command. For example to add the user skoranda run

htpasswd /srv/docker/etc/apache2/basic-auth skoranda

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@uwm.edu.

You can mock up the same behavior by simply adding the "username" scott.koranda@uwm.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-registry:/etc/apache2/sites-available/000-comanage.conf ./000-comanage.conf

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 /srv/docker/etc/apache2/
cp basic-auth /srv/docker/etc/apache2/sites-available/000-comanage.conf

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

volume:
    - /srv/docker/etc/apache2/sites-available/000-comanage.conf:/etc/apache2/sites-available/000-comanage.conf

Edit the 000-comanage.conf file and add a SetEnv directive, for example

SetEnv ENV_OIS_NAME_GIVEN Scott
SetEnv ENV_OIS_NAME_FAMILY Koranda
SetEnv ENV_OIS_MAIL skoranda@gmail.com
SetEnv ENV_OIS_EPPN scott.koranda@sphericalcowgroup.com

Restart the services and authenticate to COmanage Registry. After authenticating COmanage Registry should "see" those environment variables defined for the authenticated user.

Important Notes

The instructions above are not suitable for a production deployment since the deployed services use default and easily guessed passwords.