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

Software Prerequisites
Developer Environment
SSP Open Source Project
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

RDBMS Platform Flexibility

Currently SSP supports use of PosgreSQL or Microsoft SQL Server. The project team develops and tests against PostgreSQL and Microsoft SQL Server.

Future support for Oracle and other RDBMS is planned.

File System Layout

For development environments, it makes good sense to install Tomcat and the SSP Open Source Project and SSP Platform repositories from GitHub together in a single parent directory for the project. The examples below will use this directory as a parent

Example: C:\projects\ssp

The other components are common for Java projects and can be installed in an appropriate, general location.

uPortal Installation Instructions

Much of this process is similar to setting up uPortal. More detailed instructions for installing uPortal are available in this article or in the uPortal Manual.

Developer Environment

The following configurations are required for the developer environment.

1. Software Prerequisites and Environment Variables

Prerequisite Installations

All software prerequisites should be installed into the local environment. Make note of the locations to set the environment variables.

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/
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

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
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
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

Server Connection
1. Launch the SQL Server Management Studio application
2. Enter your database connection info including administrator account credentials, and click Connect
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
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
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" />

SSP-Open-Source-Project

The SSP-Open-Source-Project repository in GitHub contains the tool suite for SSP. Installation begins with cloning the repository.

1. Clone the SSP Open Source Project repository from GitHub

Use a command like the following to clone the SSP-Open-Source-Project repository from GitHub:

Clone Source Files

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

2. Build & Install

Use a command like the following to build the SSP-Open-Source-Project and install it in the local Maven repository:

SSP can be built in three different modes:

dev-standalone: the deployment will be completely free of uPortal (requires additional configuration)
- SSP_CONFIGDIR must be set as an environment variable instead of using context.xml
- ssp–config.properties file should be modified to uncomment spring.profiles.active=dev-standalone and comment out spring.profiles.active=uportal
- STS with embedded Tomcat is recommended to start/debug/stop the application
- You may need to add portlet-api-2.0.jar to tomcat's shared/lib (if running out of STS)
standalone: SSP will be the only deployment in uPortal
uPortal: SSP will be one of many portlets in uPortal

Maven Install Command

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

Maven Install Command Skipping Tests

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/SSP-Platform.git

2. Configure Settings

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

Edit the catalina.properties and server.xml files in Tomcat as described under "Configuring Tomcat for uPortal" on this manual page
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)
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
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)

NOTE

This command will pull the SSP-Open-Source-Project build and bundle the .war with the SSP-Platform build

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

Shreenshot

This screenshots represents a very early stage of development. Images will be updated as development progresses.

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.