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/grouperText/grouper.text.en.us.propertiesExternalized text file
/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)

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.

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

<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_SELF_SIGNED_CERT=true
(SELF_SIGNED_CERT up to v2.5.27)
will overlay /etc/httpd/conf.d/ssl-enabled.conf so that apache uses a self-signed cert for quick starts (default false)
-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_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_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_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

# 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:tomcat /opt/grouper \
  && chown -R tomcat:tomcat /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 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)

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 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:tomcat /opt/grouper \
 && 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
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