This is how the Grouper container works in v2.5
Directory structure
alpha order...
| Path | Description |
|---|---|
| /etc/httpd/conf.d/grouper-www.conf | Apache config for Grouper. Includes Shibboleth directive if using Shibboleth |
| /etc/shibboleth/shibboleth2.xml | Shibboleth config |
| /opt/grouper/ | Grouper base dir |
| /opt/grouper/grouperWebapp/ | J2EE webapp dir for grouper |
| /opt/grouper/grouperWebapp/WEB-INF/classes/ | Grouper config files |
| /opt/grouper/grouperWebapp/WEB-INF/classes/grouperText/grouper.text.en.us.properties | Externalized text file |
| /opt/grouper/grouperWebapp/WEB-INF/ddlScripts | DDL scripts that are run automatically or not, are written here |
| /opt/grouper/grouperWebapp/WEB-INF/libUiAndDaemon/ | Jars used in UI and daemon only. Place custom change log consumers here |
| /opt/grouper/grouperWebapp/WEB-INF/lib/ | Jars used in all services (UI/WS/daemon/scim). Replace database drivers or add jars for all services |
| /opt/grouper/grouperWebapp/WEB-INF/web.xml | web.xml for grouper might need security settings for authentication (e.g. tomcat LDAP authn for WS) |
| /opt/grouper/logs | If you are externalizing logs to a "mount", this is the suggested standard location |
| /opt/grouper/slashRoot | Any files or folders in here will be overlaid on / (root dir). This is useful for lower maturity levels so you only need one mount to copy files in and one mount to copy files out |
| /opt/tomee | Tomee/Tomcat app server |
| /opt/tomee/bin | Startup and shutdown scripts for tomee |
| /opt/tomee/conf/server.xml | Tomee/Tomcat server.xml might need settings for authentication (e.g. tomcat LDAP authn for WS) |
| /usr/lib/jvm/java-1.8.0-amazon-corretto | JAVA_HOME |
| /usr/lib/jvm/java-1.8.0-amazon-corretto/jre/lib/security/cacerts | cacerts for java |
Ports and configs
| Port | Service | Description | Config file |
|---|---|---|---|
| 443 | Apache | Apache listens to requests and reverse proxies to tomcat 8009. The apache URL path: /grouper → tomcat /grouper The apache URL path: /grouper-ws → tomcat /grouper The apache URL path: /grouper -scim → tomcat /grouper | /etc/httpd/conf.d/grouper-www.conf |
| 8009 | Tomee AJP | Tomcat listens here to get reverse proxied requests from apache (or another web server. Note, if you use an external apache you can link that up with the internal apache or expose the 8009 (in a secured way!) | /opt/tomee/conf/server.xml |
maps the /opt/grouper/grouperWebapp directory with | /opt/tomee/conf/Catalina/localhost/grouper.xml | ||
| 8005/8080/8443 | Tomee | These arent really used unless you configure and use them | /opt/tomee/conf/server.xml |
Grouper Container params
There are a few arguments you can pass to the container, and env vars... Note the command if specified (optional) will set env vars before the env vars. So you could call the container with "ui" but then specify that -e RUN_SHIB_SP='false' (e.g. if you run CAS)
| Argument | Description |
|---|---|
| ui | will set env vars: |
| ws | will set env vars: GROUPER_WS='true' RUN_APACHE='true' RUN_TOMEE='true' |
| scim | will set env vars: GROUPER_SCIM='true' RUN_APACHE='true' RUN_TOMEE='true' |
| daemon | will set env vars: GROUPER_DAEMON='true' RUN_TOMEE='true' |
| bin/gsh <gshScriptFileName> -or- /opt/grouper/grouperWebapp/WEB-INF/bin/gsh.sh <gshScriptFileName> | will just run gsh commands from docker command line e.g. docker run --detach --mount type=bind,src=/opt/grouperInstaller/logs,dst=/opt/grouper/logs --mount type=bind,src=/opt/grouperInstaller/slashRoot,dst=/opt/grouper/slashRoot --name gsh i2incommon/grouper:2 .5.XX /opt/grouper/grouperWebapp/WEB-INF/bin/gsh.sh /opt/grouper/grouperWebapp/WEB-INF/bin/createGrouperSystemPasswordUi.gsh |
| ui-ws | will set env vars: GROUPER_UI='true' GROUPER_WS='true' RUN_APACHE='true' RUN_SHIB_SP='true' RUN_TOMEE='true' |
| <no command> | do nothing, so GSH can be used in bash in container, or pass in ENV vars to run something not with command above |
| -e GROUPER_UI=true | env var will tell grouper to allow ui calls via grouper.hibernate.base.properties grouper.is.ui.elConfig = ${java.lang.System.getenv().get('GROUPER_UI')} |
| -e GROUPER_WS=true | env var will tell grouper to allow ws calls via grouper.hibernate.base.properties grouper.is.ws.elConfig = ${java.lang.System.getenv().get('GROUPER_WS')} |
| -e GROUPER_SCIM=true | env var will tell grouper to allow ws calls via grouper.hibernate.base.properties grouper.is.scim.elConfig = ${java.lang.System.getenv().get('GROUPER_SCIM')} |
| -e GROUPER_DAEMON=true | env var will tell grouper to kick of daemon thread in tomee grouper.is.daemon.elConfig = ${java.lang.System.getenv().get('GROUPER_DAEMON')} |
| -e RUN_APACHE=true | env var will tell supervisor to kick off apache in container. Note, apache is not needed for Grouper. You could hook up an external web server to tomee or run from tomee itself (not recommended) |
| -e RUN_SHIB_SP=true | env var will tell supervisor to kick off shib sp in container. Note if you dont use shib this is not needed. Note: you can also run shib outside the grouper container (e.g. in another container or from reverse proxy) Note: if RUN_SHIB_SP is false, it will take the shib apache directive out of grouper-www.conf |
| -e RUN_TOMEE=true | env var will tell supervisor to kick off tomee. Note you must have this to true if you are doing anything but a GSH env. The WS/UI/scim/daemon must run tomee in container. |
| -e SELF_SIGNED_CERT=true | will overlay /etc/httpd/conf.d/ssl-enabled.conf so that apache uses a self-signed cert for quick starts |
| -e GROUPER_MAX_MEMORY='3g' | set memory of java to 3 gigs. recommended 2 or 3 gig for WS and UI, and 12gig for daemon # ps -ef | grep tom (get pid) # sudo -u tomcat /usr/lib/jvm/java-1.8.0-amazon-corretto/bin/jmap -heap <pid> (see max heap, should be approx what you expect)
|
| -e GROUPER_EXTRA_CATALINA_OPTS='-XX:+PrintGCDetails' | add additional JVM options |
| -e CATALINA_OPTS='whatever' | Generally you should not set this, unless you want to override all the default tomee Grouper customizations |
Dockerfile
If you create dirs or copy things to the webapp, you should set the owner at the end of your Dockerfile
RUN chown -R tomcat:tomcat /opt/grouper/grouperWebapp
Building container
- Jenkins output (change version number): https://jenkins.testbed.tier.internet2.edu/job/docker/job/grouper/job/2.5.X/1/console
Versions
- Tag in github docker is: 2.5.X where X is an integer that increases for each build
- There is a listing of each version in the Grouper 2.5 release notes, with an indication on if it is stable or not
Misc
- HTTP Strict Transport Security (HSTS) is enabled on the Apache HTTP Server.
- morphStrings functionality in Grouper is supported. It is recommended that the various morphString files be associated with the containers as Docker Secrets. Set the configuration file properties to use `/var/run/secrets/secretname`.
- Configure Grouper UI and WS authentication
Take a heap snapshot
[root@43c6b6e000b3 ~]# sudo -u tomcat /usr/lib/jvm/java-1.8.0-amazon-corretto/bin/jmap -dump:file=/tmp/memory.dump <pid>
Jars
- If you want a jar in all JVMS (ui/ws/daemon/gsh/scim), add it to /opt/grouper/grouperWebapp/WEB-INF/lib
- If you want a jar in ui/daemon/gsh only, add it to /opt/grouper/grouperWebapp/WEB-INF/libUiAndDaemon
If you are replacing a jar (e.g. an existing driver), you need to remove it first from your dockerfile by wildcard, or overlay a blank file (risky since filenames can change)
RUN rm -rf /opt/grouper/grouperWebapp/WEB-INF/lib/mysql-connector-java*.jar
- dfs