test-compose documentation and other refinements

README.md

@@ -149,8 +149,8 @@ Secrets can be managed using the `docker secret` command: `docker secret create
 
 Bind mounts can be used to connect files/folders on the Docker host into the container's file system. Unless running in swarm mode, the secrets are not supported, so we can use a bind mount to provide the container with the configuration files.
 
-```
-docker run --detach --name daemon \
+```console
+$ docker run --detach --name daemon \
   --mount type=bind,src=$(pwd)/grouper.hibernate.properties,dst=/run/secrets/grouper_grouper.hibernate.properties \
   --mount type=bind,src=$(pwd)/sources.xml,dst=/run/secrets/grouper_sources.xml \
   tier/grouper daemon
@@ -172,8 +172,8 @@ CMD ui
 
 To build our image:
 
-```
-docker build --tag=org/grouper-ui .
+```console
+$ docker build --tag=org/grouper-ui .
 ```
 
 This image can now be used locally or pushed to an organization's Docker repository.
@@ -218,8 +218,8 @@ Using standard methods, create a MariaDb Server and an empty Grouper database. C
 
 Next populate the database by using the following command.
 
-```
-docker run -it --rm \
+```console
+$ docker run -it --rm \
   --mount type=bind,src=$(pwd)/grouper.hibernate.properties,dst=/run/secrets/grouper_grouper.hibernate.properties \
   tier/grouper gsh -registry -check -runscript -noprompt
 ```

container_files/tomcat/conf/server.xml

@@ -38,11 +38,13 @@
     <!-- Editable user database that can also be used by
          UserDatabaseRealm to authenticate users
     -->
+<!--
     <Resource name="UserDatabase" auth="Container"
               type="org.apache.catalina.UserDatabase"
               description="User database that can be updated and saved"
               factory="org.apache.catalina.users.MemoryUserDatabaseFactory"
               pathname="conf/tomcat-users.xml" />
+-->
   </GlobalNamingResources>
 
   <!-- A "Service" is a collection of one or more "Connectors" that share
@@ -113,7 +115,7 @@
     -->
 
     <!-- Define an AJP 1.3 Connector on port 8009 -->
-    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" URIEncoding="UTF-8" />
+    <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" tomcatAuthentication="false" URIEncoding="UTF-8" />
 
 
     <!-- An Engine represents the entry point (within Catalina) that processes
@@ -141,8 +143,10 @@
              resources under the key "UserDatabase".  Any edits
              that are performed against this UserDatabase are immediately
              available for use by the Realm.  -->
+<!--
         <Realm className="org.apache.catalina.realm.UserDatabaseRealm"
                resourceName="UserDatabase"/>
+-->
       </Realm>
 
       <Host name="localhost"  appBase="webapps"
@@ -164,4 +168,4 @@
       </Host>
     </Engine>
   </Service>
-</Server>
+</Server>

test-compose/README.md

@@ -1,13 +1,62 @@
-Coming soon...
+The `test-compose` directory contains an example Grouper environment that starts up the various Grouper components. This example demonstrates how one might go about customizing and deploying their Grouper containers, using the TIER Grouper image as a base image. 
 
-> This docker-stack.yml file uses the `configs` syntax which is part of the Compose file format v3.3 and requires Docker Engine version 17.06.0+ (released on 2017-06-28). Users of older engine versions will need convert `config` references to use bind mounts. After this change, everything else should work as expected.
+In this example, the following cases are covered by this example:
+
+- A demo directory and SIS database are included, populated with approximately 1,000 test subjects.
+- Grouper is configured to use this directory as the subject source.
+- Grouper Loader creates groups based on the data in the SIS table.
+- Grouper UI is protected by a Shibboleth IdP (included) that connects to this directory server.
+- Grouper WS is protected by http basic auth that authenticates against the directory server.
+- Grouper publishes event data to a RabbitMQ instance (included). 
+
+It should be noted that while this example uses Docker Compose as a build and deployment vehicle, ideally one should use a CI server to build and publish institution specific images to an image repository as changes to the institution's customizations are committed to the source repository. These images would then be deployed to Docker Swarm, assuming that the appropriate Docker Secrets and Configs have been published to the swarm.
+
+# Getting Started
+
+From `test-compose` directory, run:
+
+```console
+$ docker-compose up -d
+```
+
+This will build each of our customized images after downloading the TIER Grouper image. It will create containers for each of our components using the configuation specified in the `docker-compose.yml` file.
+
+To stop the Grouper environment, run:
+
+```console
+$ docker-compose down
+```
 
-> `configs` are not supported by docker-compose, so those are shown in the file as bind mount volumes.
+When doing iterative work, such as testing UI changes or configuration changes, I find if handy to use the following command:
 
-> Environment specific settings are passed in via secrets and configs, but anything that would standard across dev, qa, prod (e.g. jars, images, css, mods) is baked into our image.
+```console
+$ docker-compose kill; docker-compose rm -f; docker-compose build && docker-compose up
+```
 
-> The files in the `data` image's `conf` directory is used to build the sample grouper database and ldap store. It is not used when the container is instantiated.
+This command will clear out any remaining containers, as defined by the `docker-compose.yml` file, from the Docker host, rebuild our custom images, and start new instances of them. Because we do not specify the `-d` on the `up` command, the containers will not be forked causing the container logs to be displayed to the console, and the command prompt will not return until hitting `Ctrl+C`, which will kill the running containers.
 
-> Rabbit MQ: guest/guest add queue `sampleQueue` to see grouper messages.
+# Testing Endpoints
 
-> In this example we don't care about the IdP secrets. They are baked into the overlay.
+The components can be accessed at the following urls, with
+
+Grouper UI: https://localhost/grouper (username: banderson, password: password)
+Grouper WS: https://localhost:8443/grouper-ws/status?diagnosticType=all
+RabbmitMQ: http://localhost:15672/ (username: guest, password: guest) 
+MariaDB: Port 3306 (username: root, password: (no password) )
+389-ds Directory: Port 389 (username: cn=Directory Manager, password: password)
+
+Note that when accessing the Grouper UI, Grouper WS, or Shibboleth IdP, your browser will prompt you about an untrusted certificate. It is OK to ignore the warning while working with this example configuration.
+
+# Additional Notes
+
+- Docker `configs` are not supported by Docker Compose, so those are represented in the `docker-compose.yml` file as bind mount volumes.
+- The Grouper config files in the `data` image's `conf` directory are used to build the sample grouper database and ldap store. They are not used when the container is instantiated.
+- The containers will use Docker Secrets and bind mounts for non-sensitive files that are read from the `configs-ans-secrets` directory in the `test-compose` directory.
+- With regard to RabbitMQ, the deployer must manually add a queue named `sampleQueue` to see Grouper messages in RabbitMQ. Messages will be dropped by RabbitMQ until this occurs.
+- In this example, we don't care about the IdP secrets. They are baked into the overlay instead of using Docker Secrets. (This is not best practice for an IdP configuration, but that isn't the focus of this example.)
+
+# Future TODOs
+
+- Add a Docker Stack example
+
+> This docker-stack.yml file uses the `configs` syntax which is part of the Compose file format v3.3 and requires Docker Engine version 17.06.0+ (released on 2017-06-28). Users of older engine versions will need convert `config` references to use bind mounts. After this change, everything else should work as expected.

test-compose/scim/Dockerfile

@@ -2,6 +2,4 @@ FROM tier/grouper:latest
 
 LABEL author="tier-packaging@internet2.edu <tier-packaging@internet2.edu>"
 
-COPY container_files/WEB-INF/ /opt/grouper/grouper.scim/WEB-INF/
-
 CMD ["scim"]

test-compose/ui/Dockerfile

@@ -3,8 +3,5 @@ FROM tier/grouper:latest
 LABEL author="tier-packaging@internet2.edu <tier-packaging@internet2.edu>"
 
 COPY container_files/WEB-INF/ /opt/grouper/grouper.ui/WEB-INF/
-COPY container_files/tomcat/ /opt/tomcat/conf/
-
-#COPY container_files/httpd/logout.php /var/www/cgi-bin/logout.php
 
 CMD ["ui"]