Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Loading status checks…
Better documentation for simple plugin development container
@skoranda
skoranda committed Dec 15, 2020
1 parent 60a2d12 commit 13a3ca5
Showing 2 changed files with 141 additions and 58 deletions.
1 change: 1 addition & 0 deletions README.md
View file
@@ -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)
198 changes: 140 additions & 58 deletions docs/simple-development-plugin-mariadb.md
View file
@@ -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,50 +137,77 @@ 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.

* 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,23 +278,28 @@ 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
```

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,14 +308,14 @@ 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.
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.

0 comments on commit 13a3ca5

Please sign in to comment.