Add documentation for plugin development

docs/simple-development-plugin-mariadb.md

@@ -0,0 +1,239 @@
+<!--
+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, and that uses MariaDB
+for persistance storage.
+
+## Build the COmanage Registry Base Image
+
+The COmanage Registry images use [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/)
+and require that the [COmanage Registry base image](../comanage-registry-base/README.md) be built first. Follow
+the instructions for the [COmanage Registry base image](../comanage-registry-base/README.md) and build that image
+first.
+
+## Next build the COmanage Registry Basic Auth Image
+
+The [COmanage Registry with Basic Authentication](../comanage-registry-basic-auth/README.md)
+image layers on top of the base image and adds simple basic authentication.
+Follow the instructions for the [COmanage Registry with Basic Authentication](../comanage-registry-basic-auth/README.md) image
+and build that image next.
+
+## Next build the COmanage Registry for Developers Image
+
+The [COmanage Registry for Developers with Basic Authentication](../comanage-registry-basic-auth/README.md)
+image layers on top of the basic authentication image. 
+Follow the instructions for the [COmanage Registry for Developers with Basic Authentication](../comanage-registry-basic-auth-develop/README.md) image
+and build that image next.
+
+## Deploy the development sandbox
+
+* Create a directory somewhere to save the state of the COmanage Registry
+database. For example, on Linux
+
+```
+sudo mkdir -p /srv/docker/var/lib/mysql
+```
+
+On Mac OS you might instead do something like
+
+```
+mkdir -p $HOME/comanage-data/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, on Linux
+
+```
+sudo mkdir -p /srv/docker/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 mounts for your deployment.
+
+```
+version: '3.7'
+
+services:
+
+    comanage-registry-database:
+        image: mariadb:10.1
+        volumes:
+            - /srv/docker/var/lib/mysql:/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:
+            - /srv/docker/srv/comanage-registry/local:/srv/comanage-registry/local
+        environment:
+            - COMANAGE_REGISTRY_DATASOURCE=Database/Mysql
+
+        ports:
+            - "80:80"
+            - "443:443"
+```
+
+* Make sure the shell variable `COMANAGE_REGISTRY_VERSION` is 
+set, for example
+
+```
+export COMANAGE_REGISTRY_VERSION=3.3.1
+```
+
+* Start the services:
+```
+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](https://spaces.at.internet2.edu/x/FYDVCQ) for
+tips and suggestions as well as the [COmanage Coding Style](https://spaces.at.internet2.edu/x/l6_KAQ).
+
+* 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](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-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](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-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.