Skip to end of metadata
Go to start of metadata


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


grouperContainer2.5

Directory structure

alpha order...

PathDescription
/etc/httpd/conf.d/grouper-www.confApache config for Grouper.  Includes Shibboleth directive if using Shibboleth
/etc/shibboleth/shibboleth2.xmlShibboleth 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/log4j.properties

If you want to overlay this you need to set env var GROUPER_LOG_TO_HOST=false

/opt/grouper/grouperWebapp/WEB-INF/classes/log4j_additional.propertiesIf you want to append some configurations to the built-in log4j.properties, but those here (2.5.41+)
/opt/grouper/grouperWebapp/WEB-INF/classes/grouperText/grouper.text.en.us.propertiesExternalized text file (note in 2.5.33+ this can be imported into database config)
/opt/grouper/grouperWebapp/WEB-INF/ddlScriptsDDL 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.xmlweb.xml for grouper might need security settings for authentication (e.g. tomcat LDAP authn for WS)
/opt/grouper/logsIf 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.

If you have a dir in your host, lets say "/foo/bar/slashRoot", and you mount that to the container
"/opt/grouper/slashRoot", then if you make the file:
/foobar/slashRoot/opt/grouper/grouperWebapp/WEB-INF/classes/grouper.hibernate.properties,
then it will exist in the container at: /opt/grouper/grouperWebapp/WEB-INF/classes/grouper.hibernate.properties

/opt/hsqldbHSQLDB directory if using an embedded database (for quick starts or demos)
/opt/tomeeTomee/Tomcat app server
/opt/tomee/binStartup and shutdown scripts for tomee
/opt/tomee/conf/server.xmlTomee/Tomcat server.xml might need settings for authentication (e.g. tomcat LDAP authn for WS)
/usr/lib/jvm/java-1.8.0-amazon-correttoJAVA_HOME
/usr/lib/jvm/java-1.8.0-amazon-corretto/jre/lib/security/cacertscacerts for java

Ports and configs

PortServiceDescriptionConfig file
443ApacheApache 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
8009Tomee AJPTomcat 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 
the HTTP path /grouper

/opt/tomee/conf/Catalina/localhost/grouper.xml
8005/8080/8443TomeeThese arent really used unless you configure and use them/opt/tomee/conf/server.xml
9001HsqldbEmbedded database port (for quick starts and demos)
22SSHD

If you are running in a managed environment where there is no

console access, you need to have the option to have SSHD

for troubleshooting reasons (e.g. see env vars, run top, jstack,

look at config files, etc)


You can make this work however you want, here is an example from AWS ECS

Dockerfile

RUN yum install -y openssh-server
RUN ssh-keygen -t rsa -f /etc/ssh/ssh_host_rsa_key -N ''
RUN ssh-keygen -t dsa -f /etc/ssh/ssh_host_dsa_key -N ''
EXPOSE 22

Mount or overlay: /opt/tier-support/supervisord_sshd.cong

[program:sshd]
command=/usr/sbin/sshd -D
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0

Mount or overlay or edit: /usr/local/bin/grouperScriptHooks.sh

#!/bin/sh

grouperScriptHooks_setupFilesPost() {
  cp -v /opt/tier-support/supervisord.conf /opt/tier-support/supervisord.conf.origGrouper
  cat /opt/tier-support/supervisord_sshd.conf >> /opt/tier-support/supervisord.conf
  # assumes you have an env var PASS from your password manager
  echo "root:${PASS}" | chpasswd
}
export -f grouperScriptHooks_setupFilesPost

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)

ArgumentDescription
ui

will set env vars: 
GROUPER_UI='true'
GROUPER_RUN_APACHE='true'
GROUPER_RUN_SHIB_SP='true'
GROUPER_RUN_TOMEE='true'

wswill set env vars:
GROUPER_WS='true'
GROUPER_RUN_APACHE='true'
GROUPER_RUN_TOMEE='true'
scimwill set env vars:
GROUPER_SCIM='true'
GROUPER_RUN_APACHE='true'
GROUPER_RUN_TOMEE='true'
daemonwill set env vars:
GROUPER_DAEMON='true'
GROUPER_RUN_TOMEE='true'

bin/gsh  <gshScriptFileName> -or-
/opt/grouper/grouperWebapp/WEB-INF/bin/gsh.sh  <gshScriptFileName>
gsh

will just run gsh commands from docker command line e.g. (note, you need to put that file in the container e.g. with slashRoot

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

Note: this will not work with a quickstart container.  Shell into the quickstart container and run gsh.sh

ui-wswill set env vars (if not overridden):
GROUPER_UI='true'
GROUPER_WS='true'
GROUPER_RUN_APACHE='true'
GROUPER_RUN_SHIB_SP='true'
GROUPER_RUN_TOMEE='true'
quickstart   (v2.5.27+)

will set env vars (if not overridden):
GROUPER_RUN_HSQLDB=true
GROUPER_RUN_SHIB_SP=false
GROUPER_SELF_SIGNED_CERT=true
GROUPER_AUTO_DDL_UPTOVERSION='v2.5.*'
GROUPER_UI_CONFIGURATION_EDITOR_SOURCEIPADDRESSES='0.0.0.0/0'
GROUPER_START_DELAY_SECONDS=10
GROUPER_UI_GROUPER_AUTH=true
GROUPER_WS_GROUPER_AUTH=true
GROUPER_SCIM_GROUPER_AUTH=true
If a GROUPERSYSTEM_QUICKSTART_PASS is set and GROUPER_UI_GROUPER_AUTH is true (and GROUPER_QUICKSTART is true), it will configure that in grouper.hibernate.base.properties
If a GROUPERSYSTEM_QUICKSTART_PASS is set and GROUPER_WS_GROUPER_AUTH is true (and GROUPER_QUICKSTART is true),  it will configure that in grouper.hibernate.base.properties

-e GROUPER_OPENSHIFT=true

will set env vars (if not overridden):
GROUPER_CHOWN_DIRS=false
GROUPER_SHIB_LOG_USE_PIPE=false
GROUPER_GSH_CHECK_USER=false
GROUPER_RUN_PROCESSES_AS_USERS=false

<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=trueenv var will tell grouper to allow ui calls via grouper.hibernate.base.properties (default false)
grouper.is.ui.elConfig = ${java.lang.System.getenv().get('GROUPER_UI')}
-e GROUPER_WS=trueenv var will tell grouper to allow ws calls via grouper.hibernate.base.properties (default false)
grouper.is.ws.elConfig = ${java.lang.System.getenv().get('GROUPER_WS')}
-e GROUPER_SCIM=trueenv var will tell grouper to allow ws calls via grouper.hibernate.base.properties (default false)
grouper.is.scim.elConfig = ${java.lang.System.getenv().get('GROUPER_SCIM')}
-e GROUPER_DAEMON=trueenv var will tell grouper to kick of daemon thread in tomee (default false)
grouper.is.daemon.elConfig = ${java.lang.System.getenv().get('GROUPER_DAEMON')}
-e GROUPER_QUICKSTART=true
(v2.5.28+)
env var will setup quickstart components (default false)
-e GROUPER_RUN_APACHE=true

env var will tell supervisor to kick off apache in container.  Note, apache is not needed (default false)

for Grouper.  You could hook up an external web server to tomee or run from tomee itself (not recommended)

-e GROUPER_RUN_SHIB_SP=true
(RUN_SHIB_SP up to v2.5.27)

env var will tell supervisor to kick off shib sp in container.  Note if you dont use shib this is not needed. (default false)

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 GROUPER_SHIB_LOG_USE_PIPE   (v2.5.30+)env var to not setup a pipe for shib.  defaults to true. 
Set to false if should just log stdout and stderr of shib to /tmp/logshibd
Might want to mount /tmp/logshibd to the external host, or other shib log files
-e GROUPER_RUN_TOMEE=true
(RUN_TOMEE up to v2.5.27)

env var will tell supervisor to kick off tomee.  Note you must have this to true if you are doing anything  (default false)

but a GSH env.  The WS/UI/scim/daemon must run tomee in container.

-e GROUPER_RUN_HSQLDB=true    (v2.5.27+)
(RUN_HSQLDB up to v2.5.27)

env var will tell supervisor to start hsqldb, storing data files to /opt/hsqldb and listening in container on port 9001 (default false)
-e GROUPER_USE_SSL=false (v2.5.28+)if you do not want apache listening on 443 ssl.  If apache is running, default is true
-e GROUPER_WEBCLIENT_IS_SSL=false (v2.5.44+)(default is "true").  if the client to Grouper is not SSL (whether SSL is done in the Grouper container or outside), then set this to false (for browser or WS caller) so Grouper does not setup URLs back to itself with SSL
-e GROUPER_SELF_SIGNED_CERT=true
(SELF_SIGNED_CERT up to v2.5.27)

if you dont set GROUPER_SELF_SIGNED_CERT, and you have GROUPER_USE_SSL=true (default), and you dont set GROUPER_SSL_CERT_FILE, and this file doesnt exist: /etc/pki/tls/certs/host-cert.pem, then this will be true.

Means a self signed cert will be configured with apache so it will function though not ideal

-e GROUPER_SSL_USE_STAPLING=false    (v2.5.41+)set to false to turn stapling off in ssl-enabled.conf (if you don't overlay that file)
-e GROUPER_SSL_CERT_FILE=a/b/c    (v2.5.41+)Location of cert file.  If GROUPER_SELF_SIGNED_CERT!=true, this defaults to /etc/pki/tls/certs/host-cert.pem, if GROUPER_SELF_SIGNED_CERT=true, this will be /etc/pki/tls/certs/localhost.crt
-e GROUPER_SSL_KEY_FILE=a/b/d    (v2.5.41+)

Location of key file.  If GROUPER_SELF_SIGNED_CERT!=true, this defaults to /etc/pki/tls/private/host-key.pem, if GROUPER_SELF_SIGNED_CERT=true, this will be /etc/pki/tls/private/localhost.key

Note:  /run/secrets/host-key.pem will be symlinked to /etc/pki/tls/private/host-key.pem

-e GROUPER_SSL_USE_CHAIN_FILE=true|false    (v2.5.41+)true if should include an SSL chain file in the ssl-enabled.conf, false if should remove it
-e GROUPER_SSL_CHAIN_FILE=/a/b/e    (v2.5.41+)Location of chain file if GROUPER_SSL_USE_CHAIN_FILE=true.  If GROUPER_SELF_SIGNED_CERT!=true, this defaults to /etc/pki/tls/certs/cachain.pem (if that file exists), if GROUPER_SELF_SIGNED_CERT=true, this is not used since GROUPER_SSL_USE_CHAIN_FILE=true
-e GROUPER_APACHE_SERVER_NAME=https://a.b.c:443  (v2.5.28+)will set server name in grouper-www.conf and will set use canonical name on
-e GROUPER_APACHE_NONSSL_PORT=80    (v2.5.28+)will change the non-ssl port of apache.  default is 80.
-e GROUPER_APACHE_SSL_PORT=443    (v2.5.28+)will change the ssl port of apache.  default is 443.
-e GROUPER_APACHE_AJP_TIMEOUT_SECONDS    (v2.5.28+)defaults to 3600 (one hour), customize here
-e GROUPER_APACHE_DIRECTORY_INDEXES    (v2.5.30+)defaults to false.  set to true to have apache directory indexes on
-e GROUPER_APACHE_REMOTE_IP_HEADER    (v2.5.41+)e.g. X-Forwarded-For   Replaces source IP address from reverse proxy.  See apache directive RemoteIPHeader (will put in grouper-www.conf)
-e GROUPER_APACHE_REMOTE_IP_TRUSTED_PROXY   (v2.5.41+)e.g. 10.0.2.16/28.  Allows proxy from certain networks.  See apache directive RemoteIPTrustedProxy (will put in grouper-www.conf)
-e GROUPER_APACHE_STATUS_PATH (v2.5.51+)

The status path is good for monitoring (e.g. from nagios).  You can restrict the source IP address of status in the grouper.properties: ws.diagnostic.sourceIpAddresses

If nothing specified, there is a status path: /status_grouper/status

If you don't want this, set: -e GROUPER_APACHE_STATUS_PATH=none

If you want it something different, do this: -e GROUPER_APACHE_STATUS_PATH=/status2_grouper/status

-e GROUPER_TOMCAT_HTTP_PORT (v2.5.28+)defaults to 8080
-e GROUPER_TOMCAT_AJP_PORT (v2.5.28+)defaults to 8009
-e GROUPER_TOMCAT_SHUTDOWN_PORT (v2.5.28+)defaults to 8005
-e GROUPER_TOMCAT_LOG_ACCESS=true (v2.5.29+)default to false.  if you want tomcat to log access.  Apache does this too.  
-e GROUPER_TOMCAT_MAX_HEADER_COUNT=200 (v2.5.57+)due to an error in chrome 93, tomcat throws an exception about too many http headers.  The default is now 200 for tomcat, but can be customized
-e GROUPER_TOMCAT_SESSION_TIMEOUT_MINUTES=600   (v2.5.36+)tomee defaults to <session-timeout>30</session-timeout> in /opt/tomee/conf/web.xml, Grouper defaults to 10 hours (600) for UI and 1 minute fo WS.  If you use SSO without requiring reauth, then you might as well default to the SSO session length for the UI (ask your IdP operator).   Set to -2 to not change the default value in file
-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
default is 1500m (1.5gig).  Check heap is set correctly, shell in container and run

NOTE: make sure you use less memory in the JVM than the container has allocated, and this might not be what "free" or OS calls report

# 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)

Note: MEM_MAX is still used for GSH

-e GROUPER_EXTRA_CATALINA_OPTS='-XX:+PrintGCDetails'add additional JVM options.  default is blank
-e CATALINA_OPTS='whatever'

Generally you should not set this, unless you want to override all the default tomee Grouper customizations
The default Grouper settings as of v2.5.22 are: 
-XX:+UseG1GC -XX:+UseStringDeduplication

-e GROUPER_AUTO_DDL_UPTOVERSION='v2.5.*'
(v2.5.27+)
If you want Grouper to automatically install and update the database DDL when it starts up, and dont go to another minor version, anything for v2.5.*
You can instead configure this in the grouper.hibernate.properties config file with key: registry.auto.ddl.upToVersion.  Default blank
-e 

GROUPER_UI_CONFIGURATION_EDITOR_SOURCEIPADDRESSES=0.0.0.0/0
(v2.5.27+)

Allow the configuration editor in the UI only from this IP address.  Put in a cidr, or comma separated cidrs.  Or open up and trust your authn/MFA and set to 0.0.0.0/0
You can instead configure this in the grouper-ui.properties config file with key: grouperUi.configurationEditor.sourceIpAddresses
Default is 127.0.0.1/32

-e GROUPER_START_DELAY_SECONDS=10
(v.2.5.27+)
If you want Grouper to delay on startup, e.g. if waiting for the database to start.  Default is 0
You can instead configure this in the grouper.hibernate.properties config file with key: grouper.start.delay.seconds
-e GROUPER_UI_GROUPER_AUTH=true
(v.2.5.27+)
If you want to use built-in Grouper authentication for the UI before you integrate Grouper with your SSO (default false)
You can instead configure this in the grouper.hibernate.properties config file with key: grouper.is.ui.basicAuthn

-e GROUPER_WS_GROUPER_AUTH=true
(v.2.5.27+)
If you want to use built-in Grouper authentication for the WS (default false)
You can instead configure this in the grouper.hibernate.properties config file with key: grouper.is.ws.basicAuthn

-e GROUPER_WS_TOMCAT_AUTHN=true

(v.2.5.27+)

Will setup the /opt/grouper/grouperWebapp/WEB-INF/web.xml and /opt/tomee/conf/server.xml to use tomcat authentication for web services.  Note you should consider using Grouper LDAP or built in authentication instead. (default false)
-e GROUPER_SCIM_GROUPER_AUTH=true
(v.2.5.27+)
If you want to use built-in Grouper authentication for SCIM  (default false)
You can instead configure this in the grouper.hibernate.properties config file with key: grouper.is.scim.basicAuthn

-e GROUPER_MORPHSTRING_ENCRYPT_KEY_FILE=/a/b/c
(v.2.5.28+)
Location of morphString encryption key.  Note the file just has the value inside (not name=value)
You can instead configure this in the morphString.properties config file with key: encrypt.key

-e GROUPER_MORPHSTRING_ENCRYPT_KEY=myUnsecureKey
(v.2.5.27+)
morphString encryption key.  Note, passwords in environment variables or Docker commands are security risks
You can instead configure this in the morphString.properties config file with key: encrypt.key

-e GROUPER_DATABASE_URL_FILE=/a/b/c
(v.2.5.28+)

Location of the database jdbc url.  Note the file just has the value inside (not name=value)

# 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]

You can instead configure this in the grouper.hibernate.properties config file with key: hibernate.connection.url

-e GROUPER_DATABASE_URL='jdbc:postgresql://localhost:5432/database'
(v.2.5.27+)
Database URL (if not provided from file)
You can instead configure this in the grouper.hibernate.properties config file with key: hibernate.connection.url
(default jdbc:hsqldb:hsql://localhost:9001/grouper)

-e GROUPER_DATABASE_USERNAME_FILE=/a/b/c
(v.2.5.28+)
Database username from file.  Note the file just has the value inside (not name=value)
You can instead configure this in the grouper.hibernate.properties config file with key: hibernate.connection.username

-e GROUPER_DATABASE_USERNAME=grouperSchema
(v.2.5.27+)

Database username (if not provided by file)
You can instead configure this in the grouper.hibernate.properties config file with key: hibernate.connection.username
(default is: sa)

-e GROUPER_DATABASE_PASSWORD_FILE=/a/b/c
(v.2.5.28+)
Database password, should be encrypted in file.  Note the file just has the value or encrypted value (recommended) inside (not name=value)
You can instead configure this in the grouper.hibernate.properties config file with key: hibernate.connection.password

-e GROUPER_DATABASE_PASSWORD=myUnsecurePass
(v.2.5.27+)
Database password (if not provided by file).  Note, passwords in environment variables or Docker commands are security risks
You can instead configure this in the grouper.hibernate.properties config file with key: hibernate.connection.password

-e GROUPERSYSTEM_QUICKSTART_PASS=myUnsecurePass
(v.2.5.27+)
If you are running the quickstart command on the container, and you set this env var, and you are doing grouper built in authentication in the UI and/or WS, then this password will log in GrouperSystem in the UI and/or WS.  Note, this is a HUGE security problem if this is available in a production system.  GrouperSystem should not be able to log in to Grouper via WS or UI.
-e GROUPER_CHOWN_DIRS=false
(v.2.5.27+)
If you do not want the container to chown dirs that it needs owned by certain users.  If you are making a subimage, if you can 
RUN chown -R tomcat:root /opt/grouper \
  && chown -R tomcat:root /opt/tomee
Then the startup of the image will be quicker (whether or not you pass in this variable).  Docker subimages can COPY as root which negatively affects Grouper.  (default is true)
-e GROUPER_LOG_TO_HOST=true
(v.2.5.27+)
If you do not want Grouper to log to container pipes (for Maturity level 0) and you want Grouper to log to files and mount the /opt/grouper/logs dir to a host directory (default: false)

-e GROUPER_USE_GROUPER_CONTEXT=true
(v2.5.27+)

Just use /grouper as the tomcat context no matter what (see "tomcat contexts" below)  (default: false)
-e GROUPER_TOMCAT_CONTEXT=myGrouper   (v2.5.28+)Will rename the grouper.xml to be myGrouper.xml and use /myGrouper as context as far as tomcat is concerned.  If running a single component (UI/WS/SCIM), then this should match the *_URL_CONTEXT   (default: grouper unless only running WS or SCIM)
-e GROUPER_URL_CONTEXT=myGrouper   (v2.5.28+)The first part of URL for the grouper UI, defaults to "grouper"
-e GROUPERWS_URL_CONTEXT=myGrouper   (v2.5.28+)The first part of URL for the grouper WS, defaults to "grouper-ws"
-e GROUPERSCIM_URL_CONTEXT=myGrouper   (v2.5.28+)The first part of URL for the grouper SCIM, defaults to "grouper-ws-scim"
-e GROUPER_REDIRECT_FROM_SLASH_TO_GROUPER=false  (v2.5.41+)By default the container apache will redirect from / to /grouper/ .  This can be removed by setting this to false
-e GROUPERUI_LOGOUT_REDIRECTTOURL=/some/path
(v2.5.28+)
Set to grouper-ui.properties: grouperUi.logout.redirectToUrl
This will be set to /Shibboleth.sso/Logout if the shib env var is set
-e GROUPER_LOG_PREFIX=grouper   (v2.5.28+)Log prefix.  By default it is "grouper-ui' for ui-only container.  grouper-ws for ws-only.  grouper-scim for scim-only.  grouper-daemon for daemon-only.  Or "grouper" if not set to something else.
-e GROUPER_RUN_TOMCAT_NOT_SUPERVISOR=true
(v2.5.28+)

Will run the tomee process as the only process in the container, not supervisor.  Note, this is advanced, and should be run as the tomcat user.
See this wiki

-e GROUPER_RUN_PROCESSES_AS_USERS=false  (v2.5.28+)Set to false if you do not want to run processes as their default users (e.g. httpd runs as apache, tomcat runs as tomcat, shibboleth runs as shibd (this is advanced).  (default: true)
-e GROUPER_GSH_CHECK_USER=false (v2.5.28+)If you want other users to be able to run gsh.sh other than "tomcat"  (default: true)
-e GROUPER_ORIGFILE_GROUPER_XML   (v2.5.36+)Grouper will set this to true if the grouper.xml file was not replaced in subimage or slashRoot
-e GROUPER_ORIGFILE_HTTPD_CONF   (v2.5.36+)Grouper will set this to true if the httpd.conf file was not replaced in subimage or slashRoot
-e GROUPER_ORIGFILE_HTTPD_SHIB_CONF   (v2.5.36+)Grouper will set this to true if the httpd-shib.conf file was not replaced in subimage or slashRoot
-e GROUPER_ORIGFILE_LOG4J_PROPERTIES   (v2.5.36+)Grouper will set this to true if the log4j.properties file was not replaced in subimage or slashRoot
-e GROUPER_ORIGFILE_SERVER_XML   (v2.5.36+)Grouper will set this to true if the server.xml file was not replaced in subimage or slashRoot
-e GROUPER_ORIGFILE_SHIB_CONF   (v2.5.36+)Grouper will set this to true if the shib.conf file was not replaced in subimage or slashRoot
-e GROUPER_ORIGFILE_SSL_ENABLED_CONF   (v2.5.36+)Grouper will set this to true if the ssl-enabled.conf file was not replaced in subimage or slashRoot
-e GROUPER_ORIGFILE_WEBAPP_WEB_XML   (v2.5.36+)Grouper will set this to true if the WEB-INF/web.xml file was not replaced in subimage or slashRoot
-e USERTOKEN
-e ENV

This image outputs logs in a manner that is consistent with Docker Logging. Each log entry is prefaced with the submodule name (e.g. shibd, httpd, tomcat, grouper), the logfile name (e.g. access_log, grouper_error.log, catalina.out) and user definable environment name and a user definable token. Content found after the preface will be specific to the application ands its logging configuration.

Note: If customizing a particular component's logging, it is recommended that the file be source from the image (docker container cp) or from the image's source repository.

To assign the "environment" string, set the environment variable ENV when defining the Docker service. For the "user defined token" string, use the environment variable of USERTOKEN.

An example might look like the following, with the env of "dev" and the usertoken of "build-2"

shibd shibd.log dev build-2 2018-03-27 20:42:22 INFO Shibboleth.Listener : listener service starting
grouper-api grouper_event.log dev build-2 2018-03-27 21:10:00,046: [DefaultQuartzScheduler_Worker-1] INFO  EventLog.info(156) -  - [fdbb0099fe9e46e5be4371eb11250d39,'GrouperSystem','application'] session: start (0ms)
tomcat console dev build-2 Grouper starting up: version: 2.3.0, build date: null, env: <no label configured>

Grouper startup logs (v2.5.34+)

When the Grouper container starts up, it does a lot of work to manipulate the config files.  The logs are printed the container logs.  Note, this prints the bash file and function which calls the command, and prints the exit code (0 is usually success).  When it gets to "Starting supervisor" then the container should start.

grouperContainer; INFO: (library.sh) Start loading library.sh
grouperContainer; INFO: (library.sh) End loading library.sh
grouperContainer; INFO: (libraryPrep.sh-prep_conf) Start setting up initial pipes
grouperContainer; INFO: (librarySetupPipe.sh-setupPipe) Setup pipe: /tmp/logpipe
grouperContainer; INFO: (librarySetupPipe.sh-setupPipe) Setup pipe: /tmp/logsuperd
grouperContainer; INFO: (librarySetupPipe.sh-setupPipe) Setup pipe: /tmp/loggrouper
grouperContainer; INFO: (libraryPrep.sh-prep_conf) End setting up initial pipes
grouperContainer; INFO: (entrypoint.sh) Executing quickstart
grouperContainer; INFO: (libraryPrep.sh-prep_finish) End prep
grouperContainer; INFO: (librarySetupFiles.sh-setupFiles_storeEnvVars) Start store env vars in /opt/grouper/grouperEnv.sh
grouperContainer; INFO: (librarySetupFiles.sh-setupFiles_storeEnvVars) End store env vars in /opt/grouper/grouperEnv.sh
grouperContainer; INFO: (librarySetupFilesForProcess.sh-setupFilesForProcess_supervisor) Clear out supervisor.conf
grouperContainer; INFO: (librarySetupFilesApache.sh-setupFilesApache_supervisor) Appending supervisord-httpd.conf to supervisord.conf
grouperContainer; INFO: (librarySetupFilesApache.sh-setupFilesApache_selfSignedCert) cp /opt/tier-support/ssl-enabled.conf /etc/httpd/conf.d/ , result: 0
grouperContainer; INFO: (librarySetupFilesApache.sh-setupFilesApache_ports) Replace apache ssl port in ssl-enabled.conf', result: 0
patching file /etc/httpd/conf/httpd.conf
grouperContainer; INFO: (librarySetupFilesApache.sh-setupFilesApache_indexes) Patch httpd.conf to turn off indexes 'patch /etc/httpd/conf/httpd.conf /etc/httpd/conf.d/httpd.conf.noindexes.patch' result=0
grouperContainer; INFO: (librarySetupFilesTomcat.sh-setupFilesTomcat_loggingSlf4j) rm /opt/tomee/lib/slf4j-api*.jar , result: 0
grouperContainer; INFO: (librarySetupFilesTomcat.sh-setupFilesTomcat_loggingSlf4j) rm /opt/tomee/lib/slf4j-jdk*.jar , result: 0
grouperContainer; INFO: (librarySetupFilesTomcat.sh-setupFilesTomcat_loggingSlf4j) cp /opt/grouper/grouperWebapp/WEB-INF/lib/slf4j-api-*.jar /opt/tomee/lib , result: 0
grouperContainer; INFO: (librarySetupFilesTomcat.sh-setupFilesTomcat_loggingSlf4j) cp /opt/grouper/grouperWebapp/WEB-INF/lib/slf4j-jdk*.jar /opt/tomee/lib , result: 0
grouperContainer; INFO: (librarySetupFilesTomcat.sh-setupFilesTomcat_loggingSlf4j) rm /opt/grouper/grouperWebapp/WEB-INF/lib/slf4j-jdk*.jar , result: 0
grouperContainer; INFO: (librarySetupFilesTomcat.sh-setupFilesTomcat_turnOnAjp) cp /opt/tomee/conf/server.xml /opt/tomee/conf/server.xml.currentOriginalInContainer , result: 0
patching file /opt/tomee/conf/server.xml
grouperContainer; INFO: (librarySetupFilesTomcat.sh-setupFilesTomcat_turnOnAjp) Patch server.xml to turn on ajp, result: 0
grouperContainer; INFO: (librarySetupFilesTomcat.sh-setupFilesTomcat_supervisor) Append supervisord-tomee.conf to supervisord.conf
grouperContainer; INFO: (librarySetupFilesTomcat.sh-setupFilesTomcat_context) Replace context cookies in grouper.xml, result: 0
grouperContainer; INFO: (librarySetupFilesTomcat.sh-setupFilesTomcat_context) Replace tomcat context in grouper.xml, result: 0
grouperContainer; INFO: (librarySetupFilesTomcat.sh-setupFilesTomcat_context) Set contexts in grouper-www.conf and other files, results: 0 0 0 0 0 0 0 0 0
patching file /opt/tomee/conf/server.xml
grouperContainer; INFO: (librarySetupFilesTomcat.sh-setupFilesTomcat_accessLogs) Patch server.xml to not log access, result: 0
grouperContainer; INFO: (librarySetupFilesForProcess.sh-setupFilesForProcess_hsqldbVersions) rm /opt/tomee/lib/hsqldb-*.jar , result: 0
grouperContainer; INFO: (librarySetupFilesForProcess.sh-setupFilesForProcess_hsqldbVersions) cp /opt/grouper/grouperWebapp/WEB-INF/lib/hsqldb-*.jar /opt/tomee/lib/ , result: 0
grouperContainer; INFO: (librarySetupFilesForProcess.sh-setupFilesForProcess_hsqldb) Appending supervisord-hsqldb.conf to supervisord.conf
grouperContainer; INFO: (librarySetupFilesForProcess.sh-setupFilesForProcess_shib) mv /etc/httpd/conf.d/shib.conf /etc/httpd/conf.d/shib.conf.dontuse , result: 0
grouperContainer; INFO: (librarySetupFilesForProcess.sh-setupFilesForProcess_supervisorFinal) Running processes as users in supervisord.conf, result: 0
grouperContainer; INFO: (librarySetupFilesForComponent.sh-setupFilesForComponent_ws) cp -r /opt/grouper/grouperWebapp/WEB-INF/libWs/* /opt/grouper/grouperWebapp/WEB-INF/lib/ , result: 0
grouperContainer; INFO: (librarySetupFilesForComponent.sh-setupFilesForComponent_scim) cp -r /opt/grouper/grouperWebapp/WEB-INF/libScim/* /opt/grouper/grouperWebapp/WEB-INF/lib/ , result: 0
grouperContainer; INFO: (librarySetupFilesForComponent.sh-setupFilesForComponent_ui) cp -r /opt/grouper/grouperWebapp/WEB-INF/libUiAndDaemon/* /opt/grouper/grouperWebapp/WEB-INF/lib/ , result: 0
grouperContainer; INFO: (librarySetupFilesForComponent.sh-setupFilesForComponent_quickstart) edit grouper.hibernate.base.properties with UI GrouperSystem password for quick start, result: 0
grouperContainer; INFO: (librarySetupFilesForComponent.sh-setupFilesForComponent_quickstart) edit grouper.hibernate.base.properties with WS GrouperSystem password for quick start, result: 0
grouperContainer; INFO: (librarySetupFiles.sh-setupFiles_loggingPrefix) Changing log prefix to grouper in log4j.properties, result: 0
grouperContainer; INFO: (librarySetupFiles.sh-setupFiles_chownDirs) chown -R tomcat:root /opt/grouper/grouperWebapp, result: 0
grouperContainer; INFO: (librarySetupFiles.sh-setupFiles_chownDirs) chown -R tomcat:root /opt/tomee, result: 0
grouperContainer; INFO: (libraryRunCommand.sh-runCommand) Start setting up remaining pipes
grouperContainer; INFO: (librarySetupPipe.sh-setupPipe) Setup pipe: /tmp/loghsqldb
grouperContainer; INFO: (librarySetupPipe.sh-setupPipe) Setup pipe: /tmp/loghttpd
grouperContainer; INFO: (librarySetupPipe.sh-setupPipe) Setup pipe: /tmp/logtomcat
grouperContainer; INFO: (libraryRunCommand.sh-runCommand) End setting up remainder pipes
grouperContainer; INFO: (libraryRunCommand.sh-runCommand) Starting supervisor


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)

    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 variableValueCondition
    __THE_AJP_URL__ajp://localhost:8009/grouperIf the UI is running, or multiple modules (e.g. SCIM and WS)
    __THE_AJP_URL__ajp://localhost:8009/grouper-wsIf the WS is running and not UI or SCIM
    __THE_AJP_URL__ajp://localhost:8009/grouper-ws-scimIf 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:root /opt/grouper \
 && chown -R tomcat:root /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
StepFileDescription
Setup logging
Start/usr/local/bin/entrypoint.shKick off the container
prepConf()/usr/local/bin/libraryPrep.shSetup logging, needs to be first
Setup environment variables

grouperPrepConfPost()

/usr/local/bin/grouperScriptHooks.shCustom hook called at the beginning of the container startup after logging is setup
Built-in command

/usr/local/bin/daemon
/usr/local/bin/ui
/usr/local/bin/gsh
/usr/local/bin/ws
etc

Continue the workflow (below) by prepping the component, finish prep, setup files, and start supervisor
prep command:
prepUI()
prepWS()
etc
/usr/local/bin/setupPrep.shSetup each component, setting env variables

prep "only" command:
prepUIonly()
prepDaemonOnly()

/usr/local/bin/setupPrepOnly.shSet variables when certain components are the only thing runnings, can optimize
e.g. if in UI only, or WS only
E.g. set logging prefix and webapp context

grouperPrepComponentPost()

/usr/local/bin/grouperScriptHooks.shCustom hook called after the component has been prepped
Setup files
setupFiles()/usr/local/bin/librarySetupFiles.sh

Main logic that moves around files, generates files, massages files, substitutes files
Most logic is in functions that could be overridden carefully (check for changes on upgrade)
Note, this will not execute twice since GROUPER_SETUP_FILES_COMPLETE=true at end

grouperSetupFilesPost()

/usr/local/bin/grouperScriptHooks.shCustom hook called after the setupFiles functions is called, right before the process starts
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

  • If you use Kubernetes, use an ARG for the "ui" or "ws" and not a COMMAND
  • 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



  • No labels

1 Comment

  1. When checking the java heap settings, might need to start the container with strace capabilities for jmap to work properly.

    --cap-add=SYS_PTRACE