SSP Development Environment Setup

Step by step instructions for creating the environment and builds for the SSP build and platform.

1. Software Prerequisites
2. Developer Environment
3. SSP Open Source Project
4. SSP Platform

Software Prerequisites

The following software prerequisites must be installed to build and run SSP:

• JDK 1.6 update 21 or later (JDK 1.7 is not supported as of 2012/04)
  
  • http://java.sun.com (openjdk works as well)
• Tomcat 6.X (Tomcat 7 is not supported as of 2012/04)
  
  • http://tomcat.apache.org
• PostgreSQL 9.1 or Microsoft SQL Server 2005-SQL Server 2008 R2
  
  • http://www.postgresql.org
  • http://www.microsoft.com/sqlserver/
• Git
  
  • http://www.git-scm.com
• Sencha SDK
  • http://www.sencha.com/products/sdk-tools/download
• Maven 3.0.3 or later
  
  • http://maven.apache.org
  • Maven is included in the STS package and not required if STS is installed
• Ant 1.8.2 (use this exact version)
  
  • http://ant.apache.org
• Optional Software for developers
  
  • Groovy 1.8.6
    
    • http://groovy.codehaus.org
    • Only if scripts in the Groovy directory are required
  • SpringSource Tool Suite 2.9.0 or greater
    
    • http://www.springsource.org/downloads/sts
    • Only for editing the project source code, not required to simply build the project

  Unix/Linux LInks

  Creating symbolic links for the software packages (STS, Maven, Tomcat, Groovy, etc) makes upgrading the packages simpler

  Syntax: ln -s  path to executable path to link

  Example: ln -s /usr/local/springsource/sts-2.9.1.RELEASE /usr/local/sts

Developer Environment

The following configurations are required for the developer environment.

1. Software Prerequisites and Environment Variables

1. Create the following environment variables with the location of the installation
   
   • JAVA_HOME
   • GROOVY_HOME
   • ANT_HOME
   • MAVEN_HOME
   • M2_HOME
   • TOMCAT_HOME
   • SSP Environment
     • Two installations of SSP can exist on the same server to deploy the application in the web container and to execute unit tests. 
     • The paths can point to the same location as an environment variable on the machine or via setenv in Tomcat
       
       • SSP_CONFIGDIR

       • SSP_TESTCONFIGDIR

         SSP-Open-Source-Project Config Location

         Examples:

         • (Windows) C:\projects\ssp-local\config\
         • (Unix/MacOS) /opt/projects/ssp-local/config/
2. Add the following locations to the PATH environment variable
   • %MAVEN_HOME%\bin, %JAVA_HOME%\bin, %GROOVY_HOME%\bin, %ANT_HOME%\bin, <git home>\bin, <sencha_home>

2. Database Setup

You can use any supported RDBMS. Follow the steps below to setup the SSP database and login roles for the installation.

For PostgreSQL

1. Server Connection
   1. Launch the PG Admin application
   2. In the Object Browser, navigate to and right click on Server Groups -> Servers -> PostgreSQL 9.1 (localhost:5432)
   3. Click Connect and the enter the administrator password
2. Login Roles
   1. In the Object Browser, right click on Login Roles and click New Login Role

      1. In the Properties tab, enter a Role name of "sspadmin" without the quotes

      2. In the Definition tab, enter a Password of "sspadmin" without the quotes

      3. Click Ok

   2. In the Object Browser, right click on Login Roles and click New Login Role

      1. In the Properties tab, enter a Role name of "ssp" without the quotes

      2. In the Definition tab, enter a Password of "ssp" without the quotes

      3. Click Ok

   3. Confirm the new Login Roles exist in the Object Browser
3. Database
   1. In the Object Browser, right click on Databases and click New Database
      1. Enter "ssp" without the quotes as the database name
      2. Enter "sspadmin" without the quotes as the database owner
      3. Click Ok
   2. Confirm the new database exists in the Object Browser

For Microsoft SQL Server

1. Server Connection
   1. Launch the SQL Server Management Studio application
   2. Enter your database connection info including administrator account credentials, and click Connect
2. Login Roles
   1. Navigate to Security->Logins, and right click on New Login
      

      1. Login name of "sspadmin" without the quotes

      2. Select SQL Server authentication and enter a Password of "sspadmin" without the quotes

      3. Uncheck Enforce password policy

      4. Click OK

   2. Right click on Logins again, and New Login Role

   • 1. Login name of "ssp" without the quotes

     2. Select SQL Server authentication and enter a Password of "ssp" without the quotes

     3. Uncheck Enforce password policy

     4. Click OK

   1. Confirm the new users exist
3. Database
   1. Navigate to and right click on Databases and click New Database
      1. Enter "ssp" without the quotes as the database name
      2. Click OK
   2. Confirm the new database exists
   3. Run the following SQL to associate the new user accounts with the correct permissions on the new database:

      1. USE [ssp]
         GO
         IF NOT EXISTS (SELECT name FROM sys.filegroups WHERE is_default=1 AND name = N'PRIMARY') ALTER DATABASE [ssp] MODIFY FILEGROUP [PRIMARY] DEFAULT
         GO
         IF NOT EXISTS (SELECT name  FROM sys.database_principals WHERE name = 'ssp')
         BEGIN
         CREATE USER [ssp] FOR LOGIN [ssp]
         EXEC sp_addrolemember N'db_datawriter', N'ssp'
         EXEC sp_addrolemember N'db_datareader', N'ssp'
         END
         GO
         CREATE USER [sspadmin] FOR LOGIN [sspadmin]
         GO
         EXEC sp_addrolemember N'db_owner', N'sspadmin'
         GO

4. Library
   1. Download the Microsoft SQL Server JDBC driver from http://msdn.microsoft.com/en-us/sqlserver/aa937724.aspx
   2. Rename the downloaded file extension from .exe to .zip. Unzip the sqlserver-jdbc4-3.0.jar file to a directory of your choice.
   3. Setup your editor environment, or local Tomcat instance — whatever systems you will be using to run and/or test in your local environment, with an additional class path entry pointing to this JAR.
      
      

3. SpringSource Tool Suite (STS) (optional)

Follow the steps below to setup the SpringSource Tool environment

• Server
  1. In the Server tab of the Dashboard, right click and choose New -> Server
     1. Choose Apache -> Tomcat (the appropriate version of the local instance)
     2. Specify the Tomcat directory location
     3. Click Finish
  2. The Tomcat instance can now be managed from STS
• Extension
  One extension is required, Groovy Eclipse:
  1. Click the Extensions tab in the Dashboard
  2. Local and mark the checkbox for Groovy Eclipse
  3. Click Install and follow installation instructions
• Project
  1. In the Package Explorer, right click and choose New -> Project
  2. Select the appropriate Project type
  3. Enter SSP as the Project Name
  4. Enter the directory of the project in the Location
  5. Click Finish to import the SSP-Open-Source-Project into STS

4.  Application Configuration

Follow the steps below to configure the local environment

• Local Configuration
  • Local configuration files are initially placed into "project_home"\SSP-Open-Source-Project\src\main\config\external
  • Since the directory is synced with the source repository, it is necessary to maintain the local files and not sync changes with the source repository
    • Two suggested methods are available:
      • Symbolic link/Shortcut:
        1. Move the files stored in the 'external' subdirectory outside of the project folder
        2. Create a symbolic link/shortcut to the previously moved 'external' subdirectory
      • Or manually maintain files:
        1. Store a copy of the modified files outside of the project folder
        2. Manually copy the files into the project folder after syncing/cloning from the source repository

    Sync Source

    Ensure that locally modified configuration files are not committed back to the source repository

  • The following files must be modified for the installation and configuration of the local environment.
    
    • ssp-config.properties
      • The database connection parameters must be updated
    • Logging (logback.xml)
    • • Select appropriate appenders for your environment
        
        • STDOUT (the console) (disabled by default, but for development we advise you to enable it)
        • rollingFileAppender will log to SSP.log (enabled by default, but for development we advise you to disable it)
        • the e-mail appender (smtpAppender) can be enabled to send exceptions to an email address (disabledby default)
          • If using the smtpAppender, make sure you update the <property file> parameter with the location of the ssp-config.properties file. This should be the same as the SSP_CONFIGDIR environment variable and/or context.xml.
      • Edit the log levels as necessary. For example, it is advised to adjust them to the DEBUG level for development. Possibly TRACE for the org.jasig classes if you are debugging a particularly difficult bug.
        
        
• Application Context (if the environment variable for sspconfig is not set)
  
  • The Tomcat context.xml file must be updated to identify the SSP configuration directory

  • Add the following parameter to the context.xml file

    • <Parameter name="SSP_CONFIGDIR" value="location of the config files" override="false" />

      
      
      

      Tomcat context.xml

      Examples of context parameters:
      
      (Windows) <Parameter name="SSP_CONFIGDIR" value="C:\ssp-local\config\" override="false" />
      (Unix/MacOS) <Parameter name="SSP_CONFIGDIR" value="/opt/projects/ssp-local/config/" override="false" />

C:\projects\ssp>git clone git@github.com:Jasig/SSP.git

C:\projects\ssp\SSP-Open-Source-Project>mvn install

C:\projects\ssp\ssp-Open-Source-Project> mvn -Dmaven.test.skip=true install

SSP-Platform

The SSP-Platform repository in GitHub contains the runtime environment for the SSP tools and supportive technology for important web features like authentication, security, mobile device support, and administrative tools, as well as integration with CAS, Shibboleth, LDAP/Active Directory, and Grouper

1. Clone from GitHub

Use a command like the following to clone the SSP-Platform repository from GitHub:

C:\projects\ssp>git clone git@github.com:Jasig/uPortal.git

2. Configure Settings

Use the following steps to setup the SSP-Platform component:

1. Edit the catalina.properties and server.xml files in Tomcat as described under "Configuring Tomcat for uPortal" on this manual page
2. Set the value of JAVA_OPTS to be -XX:MaxPermSize=384m -Xms1024m -Xmx1024m (you can use an environment variable or edit the catalina.bat/.sh file in Tomcat)
3. Inside the SSP-Platform directory copy the build.properties.sample file to build.properties and edit the value of server.home to match the location of your Tomcat
4. Verify that the database connection settings in SSP-Platform/filters/local.properties match the database settings for SSP-Open-Source-Project;  if not, change them

3. Build & Deploy

Use the following command to build, deploy, and initialize the SSP-Platform project:

Build the full site and database: C:\projects\ssp\SSP-Platform>ant initportal


Other deployment options:

initdb: Drop uPortal tables in the db & recreate them with configured seed data (src/main/data, not including the "quickstart" folder).

deploy-ear: Build entire uPortal (incl. all wars), deploy entire uPortal to Tomcat.

deploy-war: Build & deploy _just the uPortal war_ (i.e. not portlets, etc.).

deployPortletApp: Deploy one (already-built) portlet war file to Tomcat (example ant deployPortletApp -DportletApp=..\SSP-Open-Source-Project/target/ssp.war)

4. Test Deployment

• Start Tomcat and point your browser to http://localhost:8080/ssp-platform
  Click Sign In, and use the credentials user: admin password: admin

Development Tips

General Tips:

• Use the following command to build and deploy just the SSP-Open-Source war (this is much faster than building and deploying the whole platform). It assumes that the SSP-Platform has already been initialized.

[ssp-platform-dir]>ant deployPortletApp -DportletApp={path.to.ssp-war}

• If you do not need to customize SSP, you can install it for use with uportal deployment by simply installing the war file to the maven repository of the machine doing the deployment.  You will also need the environment variables and configuration files in place.

mvn install:install-file -Dfile=<path-to-prebuilt ssp.war> -DgroupId=org.jasig.ssp \
    -DartifactId=ssp -Dversion=<version - 1.0.0-SNAPSHOT at this time> -Dpackaging=war

• The SSP-Open-Source test suite must be run on a clean, empty database. You can either delete and recreate the database, or manually run the org.jasig.ssp.dao.LiquibaseDropFirstTest tests that do this for you. Once the test suite passes, as long as you run the tests regularly with updates to the application, you shouldn't have to drop/recreate the database in most cases.

Eclipse:

• if working in SSP-Platform, and using eclipse solely as an editor, it is helpful to turn off the auto build functionality (Preferences|workspace|[uncheck Build Automatically] in Indigo)

If anything in it is incorrect or unclear, please leave a comment below.