simple-development-plugin-mariadb.md

<!--
COmanage Registry Docker documentation

Portions licensed to the University Corporation for Advanced Internet
Development, Inc. ("UCAID") under one or more contributor license agreements.
See the NOTICE file distributed with this work for additional information
regarding copyright ownership.

UCAID licenses this file to you under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with the
License. You may obtain a copy of the License at:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

# 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](https://docs.docker.com/get-docker/). These instructions require version 19.03 or higher.

* Install [Docker Compose](https://docs.docker.com/compose/install). 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](https://spaces.internet2.edu/display/COmanage/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=3.3.1
```

## Build necessary images

The COmanage Registry images use [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/).

* 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](https://spaces.at.internet2.edu/x/CgAVAg) wiki page
in the [COmanage Registry Technical Manual](https://spaces.at.internet2.edu/x/OgQFAQ).
See also the [COmanage Developer Manual](https://spaces.at.internet2.edu/x/FYDVCQ), and
specifically the wiki page on [COmanage Coding Style](https://spaces.at.internet2.edu/x/l6_KAQ).

* 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](https://en.wikipedia.org/wiki/Basic_access_authentication),
and in particular the 
[Apache HTTP Server implementation of basic authentication](https://httpd.apache.org/docs/2.4/howto/auth.html).
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](https://spaces.at.internet2.edu/x/swr9Bg)
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](https://httpd.apache.org/docs/2.4/mod/mod_env.html)
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
```

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/sites-available
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

```
volumes:
    - type: bind
      source: ${HOME}/comanage/srv/comanage-registry/local
      target: /srv/comanage-registry/local
    - type: bind
      source: ${HOME}/comanage/etc/apache2/sites-available/000-comanage.conf
      target: /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@illinois.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.