From 13a3ca5dd7d41d7d395fdf1ab3a2af617447efe2 Mon Sep 17 00:00:00 2001 From: Scott Koranda Date: Tue, 15 Dec 2020 06:33:19 -0600 Subject: [PATCH] Better documentation for simple plugin development container --- README.md | 1 + docs/simple-development-plugin-mariadb.md | 198 +++++++++++++++------- 2 files changed, 141 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index f069e45..d44a4f4 100644 --- a/README.md +++ b/README.md @@ -116,3 +116,4 @@ The following link to detailed instructions for a number of deployment scenarios * [Executing LDIF Files](docs/slapd-ldif.md) * [OpenLDAP slapd for COmanage Registry Volumes and Data Persistence](docs/openldap-volumes-and-data-persistence.md) * [Simple Development Sandbox](docs/simple-development.md) +* [Simple Plugin Development Sandbox with MariaDB](docs/simple-development-plugin-mariadb.md) diff --git a/docs/simple-development-plugin-mariadb.md b/docs/simple-development-plugin-mariadb.md index 5920d7f..a49f360 100644 --- a/docs/simple-development-plugin-mariadb.md +++ b/docs/simple-development-plugin-mariadb.md @@ -22,67 +22,112 @@ 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. +suitable for beginning COmanage Registry plugin development. This sandbox +deployment uses MariaDB for persistent storage and simple basic authentication to +COmanage Registry. -## Build the COmanage Registry Base Image +## Preliminaries -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. +* Install [Docker](https://docs.docker.com/get-docker/). These instructions require version 19.03 or higher. -## Next build the COmanage Registry Basic Auth Image +* Install [Docker Compose](https://docs.docker.com/compose/install). These instructions require +version 1.27.0 or higher. -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. +* Clone this repository: -## Next build the COmanage Registry for Developers Image +``` +git clone https://github.internet2.edu/docker/comanage-registry-docker.git +cd comanage-registry-docker +``` -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. +* 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. -## Deploy the development sandbox +Here is an example (but please check the wiki page for the latest release number): -* Create a directory somewhere to save the state of the COmanage Registry -database. For example, on Linux +``` +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: ``` -sudo mkdir -p /srv/docker/var/lib/mysql +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 ``` -On Mac OS you might instead do something like +* 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-data/var/lib/mysql +mkdir -p ${HOME}/comanage/var/lib/mysql ``` -* Create a directory somewhere for the "local" COmanage Registry +* Create a directory somewhere for the `local` COmanage Registry directory. The plugin you develop will reside under the local -directory. For example, on Linux +directory. For example ``` -sudo mkdir -p /srv/docker/srv/comanage-registry/local +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 mounts for your deployment. +database state and COmanage Registry local directories. + +***Be sure to adjust the volume source paths to use the directories you just created***. ``` -version: '3.7' +version: '3.8' services: comanage-registry-database: image: mariadb:10.1 volumes: - - /srv/docker/var/lib/mysql:/var/lib/mysql + - type: bind + source: ${HOME}/comanage/var/lib/mysql + target: /var/lib/mysql environment: - MYSQL_ROOT_PASSWORD=password - MYSQL_DATABASE=registry @@ -92,27 +137,37 @@ services: comanage-registry: image: "comanage-registry:${COMANAGE_REGISTRY_VERSION}-basic-auth-develop-1" volumes: - - /srv/docker/srv/comanage-registry/local:/srv/comanage-registry/local + - 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" ``` -* Make sure the shell variable `COMANAGE_REGISTRY_VERSION` is -set, for example +* Start the services: ``` -export COMANAGE_REGISTRY_VERSION=3.3.1 +docker-compose -p comanage up -d ``` -* Start the services: +* 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 + ``` -docker-compose up -d +[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. @@ -120,22 +175,39 @@ docker-compose up -d * 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). +* 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). + +## Stopping and removing services * To stop the services: ``` -docker-compose stop +docker-compose -p comanage stop +``` + +* To restart the services: +``` +docker-compose -p comanage start ``` -* To remove the containers and networks: +* To remove the containers and networks (database state will be saved): ``` -docker-compose down +docker-compose -p comanage down ``` -### Adding more test users +## Adding more test users -The simple development sandbox uses +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). @@ -145,23 +217,28 @@ 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 +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 /srv/docker/etc/apache2/ -cp basic-auth /srv/docker/etc/apache2/basic-auth +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 ``` -volume: - - /srv/docker/etc/apache2/basic-auth:/etc/apache2/basic-auth +volumes: + - type: bind + source: ${HOME}/comanage/srv/comanage-registry/local + target: /srv/comanage-registry/local + - type: bind + source: ${HOME}/etc/apache2/basic-auth + target: /etc/apache2/basic-auth ``` Edit the basic-auth file using the `htpasswd` command. For example @@ -180,12 +257,12 @@ 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`. +`scott.koranda@illinois.edu`. You can mock up the same behavior by simply adding the "username" -`scott.koranda@uwm.edu` with a password using the above technique. +`scott.koranda@illinois.edu` with a password using the above technique. -### Mocking Apache CGI environment variables +## Mocking Apache CGI environment variables Some COmanage Registry functionality, such as the [Env Source](https://spaces.at.internet2.edu/x/swr9Bg) @@ -201,14 +278,14 @@ 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 +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 /srv/docker/etc/apache2/ +mkdir -p ${HOME}/comanage/etc/apache2/sites-available cp basic-auth /srv/docker/etc/apache2/sites-available/000-comanage.conf ``` @@ -216,8 +293,13 @@ 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 +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 @@ -226,7 +308,7 @@ 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 +SetEnv ENV_OIS_EPPN scott.koranda@illinois.com ``` Restart the services and authenticate to COmanage Registry. @@ -234,6 +316,6 @@ After authenticating COmanage Registry should "see" those environment variables defined for the authenticated user. -### Important Notes +## Important Notes The instructions above are *not suitable for a production deployment* since the deployed services use default and easily guessed passwords.