Grouper container documentation for v2.5

The Grouper project currently supports Grouper v2.5+ running only in the i2incommon container (including of course subcontainers).  If you want to take pieces out and run in an unsupported way feel free to do that on your own.  If you have questions about how to do something with the container that you think you cannot do and think you need to do surgery, please discuss it with the Grouper team first, there is likely a way to do it with the existing container.   We are open to changing how the container is structured in v2.6, lets discuss and improve together.

This is how the Grouper container works in v2.5

Directory structure

alpha order...

Ports and configs

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 GROUPER_RUN_SHIB_SP='false'   (e.g. if you run CAS)

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

# 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.g. postgres (a):        jdbc:postgresql://localhost:5432/database
# e.g. postgres (b):        jdbc:postgresql://localhost:5432/database?currentSchema=mySchema
# e.g. mysql:           jdbc:mysql://localhost:3306/grouper?useSSL=false
# e.g. oracle:          jdbc:oracle:thin:@server.school.edu:1521:sid
# e.g. hsqldb (a):      jdbc:hsqldb:dist/run/grouper;create=true
# e.g. hsqldb (b):      jdbc:hsqldb:hsql://localhost:9001/grouper
# e.g. p6spy (log sql): [use the URL that your DB requires]

Tomcat contexts (v2.5.28+)

There is some complexity in tomcat contexts for a few reasons

1. Only one webapp should be running at a time, do not put multiple context configs in /opt/tomcat/conf/Catalina/localhost
   1. If running multiple modules (e.g. ws/ui/daemon), those run in the same webapp
2. If there is one module running, there should be a specific context config so Grouper knows the context (e.g. for SOAP WSDL), and can customize it (e.g. turn off cookies for WS/Scim)
3. The apache grouper config should dynamically adjust based on which modules are running
4. If you dont care about SOAP or cookies and just want everything in the same /grouper tomcat context, just set this env var: GROUPER_USE_GROUPER_CONTEXT=true

To customize the grouper.xml tomcat config:

1. You can overlay the /opt/tomee/conf/Catalina/localhost/grouper.xml
2. If only WS is running, then grouper.xml will be renamed grouper-ws.xml unless overridden with GROUPERWS_URL_CONTEXT
3. If only SCIM is running, then grouper.xml will be renamed grouper-ws-scim.xml unless overridden with GROUPERSCIM_URL_CONTEXT
4. Otherwise grouper.xml will remain
5. If grouper.xml remains, it will be renamed if overridden with GROUPER_TOMCAT_CONTEXT
   
   
   

   
   

To customize the /etc/httpd/conf.d/grouper-www.conf:

1. This is the base file now, use this as a template for overlays (look in container for most recent version)
   
   

    Click here to expand...

   Timeout __GROUPER_APACHE_AJP_TIMEOUT_SECONDS__
   ProxyTimeout __GROUPER_APACHE_AJP_TIMEOUT_SECONDS__
   ProxyBadHeader Ignore
   
   # the variable for _ _GROUPER_APACHE_AJP_TIMEOUT_SECONDS_ _ will be replaced to default for one hour on startup env var $GROUPER_APACHE_AJP_TIMEOUT_SECONDS
   # the variable for _ _THE_AJP_URL_ _ (no spaces) will be replaced with something like: ajp://localhost:port/grouper   on startup
   # the variable for _ _GROUPER_PROXY_PASS_ _ (no spaces) will be replaced with comment or blank on startup if running grouper url
   # the variable for _ _GROUPERWS_PROXY_PASS_ _ (no spaces) will be replaced with comment or blank on startup if running grouper-ws url
   # the variable for _ _GROUPERSCIM_PROXY_PASS_ _ (no spaces) will be replaced with comment of blank on startup if running grouper-ws-scim url
   # the variable for _ _GROUPER_TOMCAT_CONTEXT_ _ (no spaces) will be replaced with the env var $GROUPER_TOMCAT_CONTEXT
   # the variable for _ _GROUPER_URL_CONTEXT_ _ (no spaces) will be replaced with the env var $GROUPER_URL_CONTEXT
   # the variable for _ _GROUPERWS_URL_CONTEXT_ _ (no spaces) will be replaced with the env var $GROUPERWS_URL_CONTEXT
   # the variable for _ _GROUPERSCIM_URL_CONTEXT_ _ (no spaces) will be replaced with the env var $GROUPERSCIM_URL_CONTEXT
   __GROUPER_PROXY_PASS__ProxyPass /__GROUPER_URL_CONTEXT__ ajp://localhost:8009/__GROUPER_TOMCAT_CONTEXT__ timeout=__GROUPER_APACHE_AJP_TIMEOUT_SECONDS__
   __GROUPERWS_PROXY_PASS__ProxyPass /__GROUPERWS_URL_CONTEXT__ ajp://localhost:8009/__GROUPER_TOMCAT_CONTEXT__ timeout=__GROUPER_APACHE_AJP_TIMEOUT_SECONDS__
   __GROUPERSCIM_PROXY_PASS__ProxyPass /__GROUPERSCIM_URL_CONTEXT__ ajp://localhost:8009/__GROUPER_TOMCAT_CONTEXT__ timeout=__GROUPER_APACHE_AJP_TIMEOUT_SECONDS__
   
   __GROUPER_PROXY_PASS__RewriteEngine on
   __GROUPER_PROXY_PASS__RewriteRule "^/$" "/__GROUPER_URL_CONTEXT__/" [R]
   
   
   
   

2. Variables available
   
   

   Grouper apache config variable	Value	Condition
   __THE_AJP_URL__	ajp://localhost:8009/grouper	If the UI is running, or multiple modules (e.g. SCIM and WS)
   __THE_AJP_URL__	ajp://localhost:8009/grouper-ws	If the WS is running and not UI or SCIM
   __THE_AJP_URL__	ajp://localhost:8009/grouper-ws-scim	If SCIM is running and not WS or SCIM
   __GROUPER_PROXY_PASS__	<blank>	If the UI is running
   __GROUPER_PROXY_PASS__	#   (comment)	If the UI is not running
   __GROUPERWS_PROXY_PASS__	<blank>	If the WS is running
   __GROUPERWS_PROXY_PASS__	#   (comment)	If the WS is not running
   __GROUPERSCIM_PROXY_PASS__	<blank>	If SCIM is running
   __GROUPERSCIM_PROXY_PASS__	#   (comment)	If SCIM is not running

3. Use those variables in your overlay.  You should be able to have one overlay for all your environments, though maybe you want separate subimages for each env

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
RUN chown -R tomcat:tomcat /opt/tomee

Container startup workflow (v2.5.28+)

Custom overridable hooks in green

There are three main phases:

1. Setup logging
2. Setup environment variables.  Note: generally these are only set if not already set so they can be customized
3. Setup files
4. Run Processes

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
• Every container will have "yum update" done before the container is released.  As needed tomee will be updated

Misc

• All of your containers must have the correct time and consistent timezones
• 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 `/run/secrets/secretname`.
• /run/secrets 

  • If you have a secret available in /run/secrets/grouper_fileName.pass, it will be linked from  /opt/grouper/grouperWebapp/WEB-INF/classes/fileName.pass   (change fileName.pass name as needed)

  • If you have a secret available in /run/secrets/shib_fileName.pass, it will be linked from  /etc/shibboleth/fileName.pass   (change fileName.pass name as needed)

  • If you have a secret available in /run/secrets/httpd_fileName.pass, it will be linked from  /etc/httpd/conf.d/fileName.pass   (change fileName.pass name as needed)

  • If you have a secret named /run/secrets/host-key.pem, it will be linked from /etc/pki/tls/private/host-key.pem
• 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>

• See the env vars of a process, get the pid fist with ps-ef, then, run as the user (in this case tomcat) and substitute the pid in
  
  

  [root@73e1e62a5fa1 bin]# sudo -u tomcat cat /proc/45/environ | tr '\0' '\n'

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