This how-to describes how to set up a Grouper development environment so that you can code, test, and debug Grouper.
This page is specific to Grouper v2.5.
Instructions for Grouper v2.4 are found at How to Setup a Grouper Development Environment for Grouper 2.4.
This is a "no build" dev env where
Developers should understand how it works since it is a little involved
Note, if using Java 17, pass this argument to tests and tomcat
--add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED --add-opens java.sql/java.sql=ALL-UNNAMED |
|
In general the dev env uses:
|
Here are diagrams for the client (base dependency of grouper), api (next dependency), and UI (example of a third and final level dependency)
The API needs the client source and configs as linked source folders (e.g. for eclipse). This makes sure the current version of the configs and classes are in use when running tests or programs or compiling API source. |
This an example of a non-web plugin for Grouper. Pretty much all modules for Grouper look like this (except web modules like UI/WS/scim). It generally depends on the API (and transitively client). |
This is an example of the UI dev env. Note other webapps (WS/scim) will look similar. There is no build script to run Tomee against the webapp, it will just work. When you edit Java classes you might need to restart Tomee (due to hotswap) |
The example commands and screenshots are from Windows or MacOS and Eclipse, and may vary slightly for different environments. However, the overall process should be similar on any modern operating system and development tool chain. Developers can use whatever tools that let them work most efficiently.
Git for source code version control
Java - Grouper runs on Java
Apache Tomee - Grouper runs in Tomee
Database
Eclipse - Grouper development happens in Eclipse (or your favorite IDE)
If you get errors on the client about deprecated libraries, you might need to adjust your compiler errors/warnings Line endings should be unix If you get errors on maven lifecycle set this: |
The Grouper source code repository is managed in GitHub at https://github.com/Internet2/grouper.
Note: The build strategy changed for the 2.5 release. Switching between 2.4 and 2.5 branches in the same directory and workspace when developing is not recommended. Instead, keep 2.4 and 2.5 work in separate local directories each with their git repository and their own eclipse workspace. For 2.4 development see How to Setup a Grouper Development Environment for Grouper 2.4. |
Start a new eclipse workspace and import grouper modules as individual projects. Project will import as Maven projects and automatically download the required Maven dependencies. The example commands below assume the git repository was cloned to the local directory 'D:\mchyzer\git\grouper_v2_5'.
|
Run the maven grouper-parent clean and install (you can right click in eclipse on the pom and run as: maven clean, then install). you might need to delete .m2/repository/* if it is corrupt. You might need to bump up memory to 512MB to get maven to build
If there are problems in a project, you might need to right click, and do Maven → Update project When you do that, the first time, check the box to update project configuration. In all subsequent times, do NOT have the box checked to update project configuration from pom, or your settings will get undone All the projects should now be open and compiled. |
This is one of the main tricks. In my eclipse, the "conf" dir is excluded due to the pom.xml in maven Link the conf dir (even though its already a source folder) in java build path
|
We want to be able to run and debug the Grouper so that it picks up client source changes as you develop. Also needs the grouper conf per above
|
Make a java application:
|
First off, we need all the jars. You need to do this in the future if you have any class not found exceptions or weird errors, goals: dependency:copy-dependencies All jars are not in target/dependency |
We want to be able to run and debug the Grouper UI from the grouper-ui/webapp folder, so that we can work on webapp artifacts (JSPs, etc), and at the same time update Java code in the grouper project and other code locations. To do this we will update the Java Build Path output folder so that compiled classes and other artifacts go to the right directories under grouper-ui/webapp. We will also add some dependent source and library folders to the grouper-ui Java Build Path.
The grouper-ui Java Build Path should now look something like this: Add Grouper project as build path project In Grouper project, export all the maven dependencies in build path |
4. Look in Eclipse config and change all tabs to 2 spaces for indenting (search for "tab") 5. Disable folding 6. Disable spell check 7. Look in eclipse config and ignore whitespace changes 8. Settings → General → Workspace → New text file line endings → Unix |
Multiple databases are supported including Oracle, mySQL, and PostgreSQL. We’ll use PostgreSQL for this how-to. The steps for other databases would be similar. Start the development database
We will run postgres with a mounted external volume to preserve data between docker container restarts.
Connect to development database in EclipseNote, this is one way to do it. Using any other database UI browser works too. e.g. Squirrel SQL client works with all DBs
|
Create and configure the grouper-hibernate.properties for postgres (for example)
Example for HSQL database: make a file grouper/conf/grouper.hibernate.properties:
Create and configure morphString.properties
|
|
|
For development purposes, we’ll bootstrap the Grouper database, add sample subjects, and reset the database using a few Java classes. Run GrouperShell from Eclipse to initialize the Grouper database:
Run GrouperShell from Eclipse to check the Grouper database:
Run RegistryReset with ‘addSubjects’ as an argument to add sample subjects:
Query the subjects table from the Eclipse Data Source Explorer to see the added subjects: |
Preferred method in dev/test only, in a Grouper v2.5 build (maybe 2.5.25?) there is a config file override for UI/WS local basic password. in grouper-hibernate.properties add something like this
|
Run this in GrouperShell (run again with no args) though this is not ideal in dev env since unit tests delete it, use the previous method
|
Now that we have a Grouper database and some test subjects, the next step is to add the grouper-ui/webapp directory to the Eclipse Tomcat launcher so we can run and debug the grouper-ui. Replace the tomee/lib/hsql jar with the one from grouper-ui/target/dependencyAdd Tomcat server to Eclipse:
Add grouper-ui web module to Tomcat Server
Configure Server Location
Configure Tomcat Server Working Directory to direct Grouper logs
Grouper logs will now show up under ../grouper-ui/webapp/WEB-INF/logs Update conf/grouper.hibernate.properties
|
Start Tomcat from Eclipse by selecting the server under the Servers tab and clicking the green ‘Run’ button. Grouper UI should be available at http://localhost:8080/grouper. You should be able to log in with GrouperSystem or any of the test subjects and no password. Debug Grouper from Eclipse
|
Congrats! You now have a working Grouper development environment. Now go check out Grouper developers coding standards and then pick up some JIRAs!