Child pages
  • SSP Development Environment Setup
Skip to end of metadata
Go to start of metadata

 

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:

RDBMS Platform Flexibility

Icon

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

Icon

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

Icon

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

Icon

All software prerequisites should be installed into the local environment.  Make note of the locations to set the 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

          Icon

          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

      Icon

      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

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

 

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
Maven Install Command Skipping Tests

 


 

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:

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:

NOTE

Icon

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

4. Test Deployment

 

Shreenshot

Icon

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.

 

  • No labels