How To Setup a Grouper Development Environment
This how-to describes how to set up a Grouper development environment so that you can run, test, and debug the Grouper project.
The example commands and screenshots are from MacOS and may vary slightly for different environments. However, the overall process should be similar on any modern operating system and development tool chain.
Prerequisites
Git for source code version control
Install Git
$ brew install git
Or Install from package https://git-scm.com/downloads
Github Desktop is also handy
Java - Grouper runs on Java
Install OpenJDK 8 or above. Grouper runs on Java.
Apache Tomcat - Grouper runs in Tomcat
- Download and unpack Tomcat 8.5.x
Docker Desktop
- Install Docker Desktop. We’ll use this to run our development database.
Eclipse - Grouper development happens in Eclipse
- Install Eclipse IDE for Enterprise Java Developers or similar IDE
Clone the Grouper Source Repository
The Grouper code repository is available on https://github.com/Internet2/grouper
- git clone --depth 1 https://github.com/Internet2/grouper.git grouper-2.5
It is recommend not to switch between 2.4 and 2.5 branches in the same directory and workspace when developing since it makes keeping development environment straight difficult. Instead keep 2.4 and 2.5 work in separate local repos each with their own eclipse workspace.
To developer on 2.4
- git clone --depth 1 https://github.com/Internet2/grouper.git grouper-2.4
- git checkout GROUPER_2_4_BRANCH
Import Projects into Eclipse
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 '/Users/thompsow/src/grouper-2.5/'.
- Import grouperClient
- Eclipse -> File -> Open Projects for File System or Archive
- Import source: /Users/thompsow/src/grouper-2.5/grouper-misc/grouperClient
- Import the grouper
- Eclipse -> File -> Open Projects for File System or Archive
- Import source: /Users/thompsow/src/grouper-2.5/grouper
- Import grouper-ui
- Eclipse -> File -> Open Projects for File System or Archive
- Import source: /Users/thompsow/src/grouper/grouper-ui
- Import grouper-ws
- Eclipse -> File -> Open Projects for File System or Archive
- Import source: /Users/thompsow/src/grouper/grouper-ws/grouper-ws
All the project should now be open and compiled.
Link source and conf to grouper-ui project
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.
- grouper-ui -> File -> Properties -> Java Build Path -> Source tab
- Set ‘Default output folder:’ to: grouper-ui/webapp/WEB-INF/classes (you may have to create this directory)
- Add dependent source and configuration folders to the Java Build Path
- Click ‘Link Source…’
- Click ‘Variables…’
- Click ‘New…’
- Name: GROUPER_REPO
- Click ‘Folder…’ and select the root repo folder
- Select GROUPER_REPO
- Click ‘Extend…’
- Select ‘grouper/conf’
- Folder name: grouper-conf
- Click ‘Link Source…’
- Click ‘Variables…’
- Select GROUPER_REPO
- Click ‘Extend…’
- Select ‘grouper/src/grouper’
- Folder name: grouper-src
- Click ‘Link Source…’
- Click ‘Variables…’
- Select GROUPER_REPO
- Click ‘Extend…’
- Select ‘grouper-misc/grouperClient/src/java
- Folder name: grouperClient-src
- Click ‘Link Source…’
- Click ‘Variables…’
- Select GROUPER_REPO
- Click ‘Extend…’
- Select ‘grouper-misc/grouperClient/conf’
- Folder name: grouperClient-conf
- Grouper Configuration
- Grouper source
- GrouperClient source
- GrouperClient configuration
- Make sure all folders except ‘grouper-ui/java/test’ are using the default output folder
- Make sure grouper-ui/conf has ‘Excluded:’ set to (None)
- Remove srcPoc and misc source folders (these are not needed)
The grouper-ui Java Build Path should now look something like this:
Add runtime jars to grouper-ui Java Build Path
We need to pull dependent jar files into grouper-ui/webapp/WEB-INF/lib directory. We’ll do this by adding three more “source” folders to the grouper-ui Java Build Path.
- grouper-ui -> File -> Properties -> Java Build Path
- Link Source…
- Linked folder location: GROUPER_REPO/grouper/lib/grouper
- Folder name: grouper-lib
- Configure grouper-lib source to output to path relative to ‘grouper-ui’
- Check “Allow output folders for source folders
- Click “Output folder” on grouper-lib
- Select ‘Specific output folder (path relative to ‘grouper-ui’)
- create/select ‘webapp/WEB-INF/lib’
- create/select ‘webapp/WEB-INF/lib’
- Add grouper jars
- Add jdbc sample jars
- Link Source…
- Linked folder location: /Users/thompsow/src/grouper/grouper/lib/jdbcSamples
- Folder name: jdbcSamples-lib
- Configure grouper-lib source to output to path relative to ‘grouper-ui’
- webapp/WEB-INF/lib
- Link Source…
- Add grouper-ui jars
- Add Folder…
- Select java/lib
- Check “Allow output folder for source folders
- Configure grouper-lib source to output to path relative to ‘grouper-ui’
- webapp/WEB-INF/lib
- Add javax.servlet.jsp-api.{version}.jar to Exclusion patterns
- Add Folder…
The grouper-ui Java Build Path should now look something like this:
Configure Eclipse Code Formatter
- Eclipse -> Preferences -> Java Code Style -> Formatter
- Import… (navigate and select ../grouper/grouper/misc/eclipse/fastFormat.xml)
- Apply and close
Development Database
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.
- Create directory ‘$HOME/docker/volumes/postgres’
- Run ‘docker run --name grouperdb -e POSTGRES_PASSWORD=grouper -e POSTGRES_USER=grouper -d -p 5432:5432 -v $HOME/docker/volumes/postgres:/var/lib/postgresql/data postgres’
Connect to development database in Eclipse
- Window -> Perspective -> Open Perspective -> Other -> Database Development -> Open
- Right click ‘Database Connections’ and create PostgreSQL connection profile
Add the postgess JDBC driver found in under ../grouper/grouper-ui/webapp/WEB-INF/lib/
Enter the connection details and then click Test Connection
Configure minimum properties files for development
Create and configure the grouper-hibernate.properties for postgres
- cd ../grouper/grouper/conf
- cp ../misc/grouper.hibernate.example.properties grouper.hibernate.properties
- Edit ../grouper/grouper/conf/grouper.hibernate.properties
Create and configure morphString.properties
- $ cp ../misc/morphString.example.properties morphString.properties
- Edit ../grouper/grouper/conf/morphString.properties
- encrypt.key = not_a_random_key
Create properties files
- cd ../grouper/grouper/conf
- $ cp log4j.example.properties log4j.properties
- $ cp ../misc/grouper.example.properties grouper.properties
- $ cp ../misc/grouper.cache.example.properties grouper.cache.properties
- $ cp ../misc/subject.example.properties subject.properties
- ...argh have to copy all the *.example.properties to *.properties how to handle this?
- $ cp grouperText/grouper.textNg.en.us.base.properties grouperText/grouper.text.en.us.properties
Bootstrap the Grouper Database
For development purposes, we’ll bootstrap the Grouper database, add sample subjects, and reset the database using a few Java classes. To initialize the Grouper database we will run the GrouperShell class with arguments “-registry -runscript -noprompt”.
Run GrouperShell from Eclipse to initialize the Grouper database:
- Right click GrouperShell in the grouper project explorer
- Select ‘Run as’ and then ‘Run Configurations…’
- Name: GrouperShell -registry -runscript -noprompt
- (x) = Arguments tab
- Program arguments:
- -registry -runscript -noprompt
- Classpath tab
- Highlight User Entries and click ‘Advanced…’
- Add the ‘conf’ folder to the classpath for the properties files
- Click ‘Apply’
- Click ‘Run’
Run GrouperShell from Eclipse to check the Grouper database:
- Right click GrouperShell in grouper project explorer
- Select ‘Run as’ and then ‘Run Configurations…’
- Name: GrouperShell -registry -check -noprompt
- (x) = Arguments tab
- Program arguments:
- -registry -check -noprompt
- Classpath tab
- Highlight User Entries and click ‘Advanced…’
- Add the ‘conf’ folder to the classpath
- Click ‘Apply’
- Click ‘Run’
Run RegistryReset with ‘justAddSubjects’ as an argument to add sample subjects:
- Right click RegistryRest in grouper project explorer
- Select ‘Run as’ and then ‘Run Configurations…’
- Name: RegistryReset justAddSubjects
- (x) = Arguments tab
- Program arguments: