This page is out of date as of May 2020. 
See this page to learn about the getting started quickly for Grouper v 2.5+


This page is instructions on how to get going with Grouper quickly, as an example from Penn.  There are other quick starts for Grouper, this is another one.

API:

  1. Unzip or checkout grouper api
    1. e.g. for the 1.4 branch
      git clone https://github.com/Internet2/grouper.git
      git checkout --track origin/GROUPER_1_4_BRANCH
  2. Run: ant dist
  3. Hsql doesnt work too well, so switch to mysql.  Create a schema and user in mysql (e.g. grouperuser@localhost).  I recommend the free version of sqlyog to manage mysql.
  4. Change these settings in conf/grouper.hibernate.properties 

    hibernate.dialect                 = org.hibernate.dialect.MySQL5Dialect
    hibernate.connection.driver_class = com.mysql.jdbc.Driver
    hibernate.connection.url          = jdbc:mysql://localhost:3306/grouper?useSSL=false
    hibernate.connection.username     = grouper
    hibernate.connection.password     = whateverYouSet
    


  5. Copy the grouper_home/lib/jdbcSamples/mysql-connector-java-bin.jar to grouper_home/lib/custom
  6. Add tables: bin\gsh -registry -runscript
    1. If there is an error, check the logs carefully, check the db, to be sure it failed.  If a lot of views are there, things might be ok.  If grouper_fields is empty, run: bin\gsh -registry -reset
    2. You should now be able to browse the DB with sqlYog or whatever tool you use to admin the db
  7. Check tables:  bin\gsh -registry -check
    1. Should output: NOTE: database table/object structure (ddl) is up to date
  8. Start gsh and add a subject: bin\gsh
    1. gsh 0% addSubject("mchyzer", "person", "Chris Hyzer")
      gsh 1% exit
  9.  In grouper.properties, I will change/add these settings:

    groups.wheel.use                      = true
    groups.wheel.group                    = etc:sysadmingroup
    configuration.autocreate.group.name.0 = etc:sysadmingroup
    configuration.autocreate.group.description.0 = super users
    configuration.autocreate.group.subjects.0 = mchyzer
    configuration.autocreate.group.name.1 = etc:webServiceUsers
    configuration.autocreate.group.description.1 = users allowed to log in to the WS
    configuration.autocreate.group.subjects.1 = mchyzer
    configuration.autocreate.group.name.2 = etc:webServiceActAsUsers
    configuration.autocreate.group.description.2 = users allowed to act as other in the WS
    configuration.autocreate.group.subjects.2 = mchyzer
    


  10. Start gsh again: bin\gsh      see if the user is in the groups
    1. gsh 0% grouperSession = GrouperSession.startRootSession();
      edu.internet2.middleware.grouper.GrouperSession: f802d876-b876-4315-b76e-0586bcc561b1,'GrouperSystem','application'
      gsh 1% subject = findSubject("mchyzer");
      subject: id='mchyzer' type='person' source='jdbc' name='Chris Hyzer'
      gsh 2% member = MemberFinder.findBySubject(grouperSession, subject);
      member: id='mchyzer' type='person' source='jdbc' uuid='1324c75e-9435-4c45-97e9-af40f2b71046'
      gsh 3% member.getGroups();
      group: name='etc:sysadmingroup' displayName='etc:sysadmingroup' uuid='38990f70-3d93-4a80-933c-6358c524024c'
      group: name='etc:wsActAsUsers' displayName='etc:webServiceActAsUsers' uuid='e87171ed-69e4-4cf8-91ea-c463770b71b1'
      group: name='etc:wsUsers' displayName='etc:webServiceUsers' uuid='6b2928d8-08f7-4cab-91f0-cb42dc794456'
      group: name='etc:uiUsers' displayName='etc:userInterfaceUsers' uuid='4103ede1-fdd1-419b-a5a7-0d2a6b3220eb'
      gsh 4%
  11. If you want quickstart data, download this file into quickstart.xml, and this file into subjects.sql.  (note, you need to act as admin, or adjust permissions to see this data, but you can verify in the DB that there a lot of groups/stems/etc)
    1. Import with: bin\gsh -registry -runsqlfile subjects.sql
    2. Import with: bin\gsh -xmlimport GrouperSystem quickstart.xml

Grouper UI

  1. Download or unzip grouper-ui
    1. e.g. for the 1.4 branch
  2. Run ant    -   exit
  3. Edit the build.properties,
    1. set the grouper.folder if not ../grouper
    2. set dist.home,  e.g. dist.home=dist
    3. set no metainf context: should.copy.context.xml.to.metainf=false
  4. Run ant    -    dist
  5. Edit your tomcat_home/conf/server.xml, add a context for the UI
    1. <Engine defaultHost="localhost" name="Catalina">
        <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/>
        <Host appBase="webapps" autoDeploy="true" name="localhost" unpackWARs="true" xmlNamespaceAware="false" xmlValidation="false">
          <Context docBase="C:\dev_inst\eclipse\workspace_v33\grouper-ui\dist\grouper" path="/grouper" reloadable="false"/>
        </Host>
      </Engine>
    2. Edit the <Connectors to have uri encoding of utf8
      <Connector  URIEncoding="UTF-8"
  6. Add the user/pass to your tomcat_home/conf/tomcat-users.xml
    1. <tomcat-users>
        <role rolename="grouper_user"/>
        <user username="mchyzer" password="whateveryouwant" roles="grouper_user"/>
      </tomcat-users>
  7. Start tomcat
  8. Go to URL: http://localhost:8080/grouper (or wherever you mapped this to tomcat)
  9. You should be able to login with the credentials in the tomcat-users.xml, and you should see the act as admin dropdown in the upper right

Grouper Web Services

  1. Checkout or download grouper web services
    1. e.g. for the 1.4 branch
  2. Stop tomcat
  3. Do a build in ws: ant quick
  4. Change these settings in the build.properties:
    1. grouper.lib.dir=../grouper/lib/grouper
      grouper.jar.name=../grouper/dist/lib/grouper.jar
      grouper.conf.dir=../grouper/conf
      generated.client.project.dir=../grouper-ws-java-generated-client_HEAD
  5. Edit these lines in the grouper-ws.properties
    1. ws.act.as.group = etc:webServiceActAsUsers
      ws.client.user.group.name = etc:webServiceUsers
  6. Do another build: ant quick
  7. Edit your tomcat_home/conf/server.xml, add a context for the WS
    1. <Engine defaultHost="localhost" name="Catalina">
        <Realm className="org.apache.catalina.realm.UserDatabaseRealm" resourceName="UserDatabase"/>
        <Host appBase="webapps" autoDeploy="true" name="localhost" unpackWARs="true" xmlNamespaceAware="false" xmlValidation="false">
          <Context docBase="C:\dev_inst\eclipse\workspace_v33\grouper-ui\dist\grouper" path="/grouper" reloadable="false"/>
          <Context docBase="C:\dev_inst\eclipse\workspace_v33\grouper-ws_HEAD\build\dist\grouper-ws" path="/grouperWs" reloadable="false"/>
        </Host>
      </Engine>
  8.  Start tomcat

Grouper Client

  1.  Download or checkout grouper client
    1. e.g. for the 1.4 branch
  2. Run from grouper_client_home: ant
  3. Customize these in the conf/grouper.client.properties
    1. grouperClient.webService.url = http://localhost:8090/grouperWs/servicesRest
      grouperClient.webService.login = mchyzer
      grouperClient.webService.password = whateveryouwant
  4. Do another build: ant
  5. Cd to the institution dir, and try to run the grouper client:
    1.  F:\temp\grouperClientTemp\dist\institution\grouperClient.institution-1.4.0-rc2> java -jar grouperClient.jar --operation=getGroupsWs --subjectIds=mchyzer
      SubjectIndex 0: success: T: code: SUCCESS: subject: mchyzer: groupIndex: 0: etc:sysadmingroup
      SubjectIndex 0: success: T: code: SUCCESS: subject: mchyzer: groupIndex: 1: etc:webServiceActAsUsers
      SubjectIndex 0: success: T: code: SUCCESS: subject: mchyzer: groupIndex: 2: etc:webServiceUsers
      SubjectIndex 0: success: T: code: SUCCESS: subject: mchyzer: groupIndex: 3: etc:userInterfaceUsers

F:\temp\grouperClientTemp\dist\institution\grouperClient.institution-1.4.0-rc2>

  1. asdf

Hsql

To use hsql, you should go in server mode.  To do this,

F:\temp\grouper1.4\grouper-api-1.4.1\bin>java -cp ..\lib\jdbcSamples\hsqldb.jar org.hsqldb.Server -database.0 file:grouper -dbname.0 grouper

* Change your grouper.hibernate.properties:

hibernate.dialect               = org.hibernate.dialect.HSQLDialect
hibernate.connection.driver_class = org.hsqldb.jdbcDriver
hibernate.connection.url = jdbc:hsqldb:hsql://localhost/grouper
hibernate.connection.username         = sa
hibernate.connection.password         =

* Start admin tool if you like

F:\temp\grouper1.4\grouper-api-1.4.1\bin>java -cp ..\lib\jdbcSamples\hsqldb.jar org.hsqldb.util.DatabaseManager -url jdbc:hsqldb:hsql://localhost/grouper

* To delete the database, delete the files from the dir where you started hsqldb: grouper.log, grouper.properties, grouper.script