SSP Developer Installation Instructions

Step by step instructions for building and deploying the SSP source packages.

1. Software Prerequisites (JDK, Tomcat, Maven, Ant, Sencha SDK Tools, RDBMS)
2. SSP Open Source Project build and deployment
3. SSP Platform build and deployment

Software Prerequisites

The following software prerequisites must be installed with the appropriate environment variables to build and run SSP:

• JDK 1.7 only starting with v2.6.0 (master branch as of 9/1/2014).
  
  • Download Location: http://java.sun.com

  • Environment Variable: JAVA_HOME

    Java Environment Variable

    JAVA_HOME=/path/to/your/java (ie: /usr/local/java or C:\java\jdk)
    
    

    
    (optional)
    PATH= append the bin subdirectory to the path statement

• Tomcat 6.X (Tomcat 7 is not supported as of 2013/01)
  

  • Instructions for installing and configuring Tomcat for the SSP-Platform (uPortal 4.0)

    Tomcat Configuration

    It is important to complete sections: Environment Variables, Shared Libraries, Shared Sessions, Java Heap

  • The following are the key parts of the document linked above if you have already installed tomcat.
    
    

    • Edit CATALINA_BASE/conf/catalina.properties to include the shared library folders in the tomcat directory. You may need to create these folders depending on your system permissions, as well as include an absolute path instead of ${catalina.base} if the environment variables are not set correctly.

      shared.loader=${catalina.base}/shared/classes,${catalina.base}/shared/lib/*.jar

      Symptoms of not including this change

      localhost.<date>.log file will throw java.lang.ClassNotFoundException: javax.portlet.PortletMode exception as you start tomcat.

    • Edit CATALINA_BASE/conf/server.xml to allow the portlets to share user session data.

      <Connector port="8080" protocol="HTTP/1.1"
          connectionTimeout="20000" redirectPort="8443" emptySessionPath="true"/>

      Symptoms of not including this change

      If you go to localhost:8080/ssp-platform and login successfully, upon loading the SSP Portlet does not appear.

    • Edit CATALINA_BASE/bin/setenv.[sh|bat]

      Increase the heap in <tomcat>/bin/setenv.sh (*nix) or <tomcat>/bin/setenv.bat (Windows). Smaller sizing is probably feasible, but the examples below match what our SSP CI envs run with. For production systems, start with a max heap of roughly half available physical memory and increase from there if necessary.

      The uPortal instructions above recommend using JAVA_OPTS for heap sizing. This can lead to problems on memory constrained systems because JAVA_OPTS will be used when trying to stop Tomcat with its own scripts. You don't typically need a large heap at all for that operation. So CATALINA_OPTS is a better choice for sizing the heap in setenv scripts, because that var will only be used for Tomcat's http-serving runtime.

      setenv.sh:

      CATALINA_OPTS=-Xms2G -Xmx2G -XX:PermSize=256m -XX:MaxPermSize=256m

      setenv.bat (uPortal instructions linked to above are missing the 'set'):

      set CATALINA_OPTS=-Xms2G -Xmx2G -XX:PermSize=256m -XX:MaxPermSize=256m

       

       

      Symptoms of not including this change

      PermGen space errors reported in catalina.out as tomcat attempts to start.

    • 
      

    • 
      

• Maven 3.0.3 or later
  
  • Download Loation: http://maven.apache.org

  • Environment Variable: MAVEN_HOME

    Maven Environment Variables

    MAVEN_HOME= /path/to/your/maven (ie: /usr/local/maven or C:\tools\maven)

    M2_HOME= /path/to/your/maven (ie: /usr/local/maven or C:\tools\maven)

    
    (optional)
    PATH= append the bin subdirectory to the path statement

• Ant 1.8.2 (use this exact version)
  

  • Download Location: http://ant.apache.org

  • Environment Variable: ANT_HOME

    Ant Environment Variable

    ANT_HOME= /path/to/your/ant (ie: /usr/local/ant or C:\tools\ant)
    
    (optional)
    PATH= append the bin subdirectory to the path statement

• Sencha SDK Tools (current version 2.0.0.0 beta 3
  
  • Download Location: http://www.sencha.com/products/sdk-tools/download/
  • Environment Variable not required, but helpful in adding to path
  • Windows x64 users will also need to install a 32-bit Java SDK/JRE for the sencha build command to work properly (one of the jars in sencha looks for the 32-bit runtime and won't play nicely with the 64-bit SDK/JRE.)
  • See  SSP Sencha Build Tool Usage for additional installation steps on 64-bit OSs
    

     

    Sencha SDK Tools

    PATH= append the Sencha SDK Tools installation directory (not the bin)

• RDBMS (support for PostgreSQL and Microsoft SQL Server)
  
  • PostgreSQL 9.1 or later
    
    • Download Location: http://www.postgresql.org
      
      • On Unix:
        
        • PostgreSQL is available in the package manager of most linux distributions.
          
          • Install it according to the distribution's instructions
        • Ubuntu - https://help.ubuntu.com/11.10/serverguide/C/postgresql.html
      • On Mac:
        
        • PostgreSQL is available via the homebrew package manager or as a download on the postgresql.org site.
      • On Windows:
        
        • PostgreSQL is available as a download on the postgresql.org site.
    • Configure PostgreSQL
      
      • Server Connection
        
        • Launch the PG Admin application
        • In the Object Browser, navigate to and right click on Server Groups -> Servers -> PostgreSQL 9.1 (localhost:5432)
        • Click Connect and the enter the administrator password
      • Login Roles
        
        • In the Object Browser, right click on Login Roles and click New Login Role
          

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

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

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

          
          

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

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

        • Confirm the new Login Roles exist in the Object Browser
      • Database
        
        • In the Object Browser, right click on Databases and click New Database
          
          • Enter "ssp" without the quotes as the database name
          • Enter "sspadmin" without the quotes as the database owner
        • Confirm the new database exists in the Object Browser
  • Microsoft SQL Server 2008 or 2008 R2
    
    • Server Connection
      
      • Launch the SQL Server Management Studio application
      • Enter your database connection info including administrator account credentials, and click Connect
    • Login Roles
      
      • Navigate to Security->Logins, and right click on New Login
        
        • Login name of "sspadmin" without the quotes
        • Select SQL Server authentication and enter a Password of "sspadmin" without the quote
        • Uncheck Enforce password policy
      • Right click on Logins again, and New Login Role
        
        • Login name of "ssp" without the quotes
        • Select SQL Server authentication and enter a Password of "ssp" without the quote
        • Uncheck Enforce password policy
      • Confirm the new users exist
    • Database
      
      • Navigate to and right click on Databases and click New Database
        
        • Enter "ssp" without the quotes as the database name
      • Confirm the new database exists

  • Run the following SQL to assign user permissions and configure the required database settings

     

    SQL Server Configurations

    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
    

    For MSSQL 2008 or later:
    
    ALTER DATABASE ssp
     SET ALLOW_SNAPSHOT_ISOLATION ON
    ALTER DATABASE ssp
     SET READ_COMMITTED_SNAPSHOT ON

    Also note that for SQLServer the "operational" SSP database user ('ssp' in the example above) must be allowed to execute stored procedures. In most deployments this does not require special configuration, but in the event your security policies are such that that user must be explicitly granted execute permissions on specific stored procs, here are the statements which you would likely need to run. (Use 'dbo' for <schema> unless you know the value should be something else (db_schema from $SSP_CONFIGDIR/ssp-config.properties); use 'ssp' for <ssp-operational-user> unless you've chosen a different name for that account (db_username from $SSP_CONFIGDIR/ssp-config.properties).):

    GRANT EXEC on <schema>.REFRESH_MV_DIRECTORY_PERSON to <ssp-operational-user>;
    GRANT EXEC on <schema>.REFRESH_MV_DIRECTORY_PERSON_BLUE to <ssp-operational-user>;
    GRANT EXEC on <schema>.update_directory_person_from_view_where_school_id to <ssp-operational-user>;
    GRANT EXEC on <schema>.update_directory_person_from_view_where_person_id to <ssp-operational-user>;

Configure and Deploy SSP

The following configurations are required to build and deploy SSP.

1. Create Directories

• Create a directory for the source files
  
  • Unix/Linux/Mac example: /usr/local/ssp

  • Windows example: C:\ssp

• Make the directory only readable by the user that is running Tomcat

  
  

  • Unix/Linux/Mac example: /usr/local/ssp/ssp-local

  • Windows example: C:\ssp\ssp-local

• Set an Environment Variable for the local configuration file location

  SSP_CONFIGDIR=/path/to/your/local-configuration (ie: /usr/local/ssp/ssp-local or C:\ssp\ssp-local)

2. Clone the SSP Open Source Project repository from GitHub

The SSP-Open-Source-Project repository in GitHub contains the tool suite for SSP.  Installation begins with cloning the repository.  Two methods exist for obtaining the source files.

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

3. Modify SSP Configuration Files

• Context.xml
  
  • A context.xml file is copied into the conf directory of Tomcat once the SSP application starts.  It can be edited prior to deployment or the file can be edited after the deployment.
  • File Location: src/main/webapp/META-INF/context.xml
  • Configuration Values: SSP configdir parameter

    <Parameter name="SSP_CONFIGDIR" value="C:/ssp/ssp-local" /> 

• ssp-config.properties
  
  • The ssp-config.properties file must be modifed for database connectivity and email settings
  • File Location: src/main/config/external to /usr/local/etc/ssp or C:\ssp (depending on the environment

  • Action: copy the  ssp-config.properties file to the local configuration directory (ie: C:\ssp\ssp-local)

  • Configuration Values:

db_liquibase_manage_external_database_by_default

db_batchsize 

cacheLifeSpanInMillis 

• logback.xml
  
  • The logback.xml controls the log location and level
  • File Location: src/main/config/external to /usr/local/etc/ssp or C:\ssp (depending on the environment

  • Action: copy the  logback.xml file to the local configuration directory (ie: C:\ssp\ssp-local)

  • Configuration Values: property file
    
    
  logback.xml

  <property file="C:/ssp/ssp-local/ssp-config.properties"

   

  • Additional configuration options
    
    • Adjust the log levels for each log appender as necessary
    • Enable the smtpAppender (disabled by default)
    • Further details regarding managing the logback.xml are included in XML comments within the file
      
      

4.  Build SSP

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

C:\ssp\SSP-master>mvn install

C:\ssp\SSP-rel-1-1-0> mvn -Dmaven.test.skip=true install

C:\ssp\SSP-rel-1-1-0> mvn -PSKIP_SENCHA clean install

Configure and Deploy SSP-Platform

The following configurations are required to build and deploy SSP-Platform.

1. Clone the SSP-Platform repository from GitHub

The SSP-Platform repository in GitHub contains the tool suite for SSP.  Installation begins with cloning the repository.  Two methods exist for obtaining the source files.

C:\\SSP-Platform>git clone -b ssp-master git@github.com:Jasig/uPortal.git

2. Modify SSP-Platform Configuration Files

• build.properties
  
  • The build.properties.sample file is copied or renamed in the current directory.  The parameter defines the location of Tomcat.
  • File Location: (uPortal-ssp-1-0-0)
  • Configuration Values: server.home parameter

server.home=D:/apps/tomcat6

• pom.xml (ONLY for non-JTDS jdbc driver installations on Microsoft SQL Server.  SSP-Platform now supports JTDS driver in the package)
  

  • JDBC driver for SSP-Platform if not using PostgreSQL

    The pom.xml should only be changed with extreme care.  This is only required for Microsoft SQL Server installations not using the default JTDS jdbc driver packaged with SSP-Platform.  The parameter defines the location of the driver in the local repository.

  • File Location: (uPortal-ssp-1-0-0)

  • Configuration Values: parameters

  • Action: modify the exist parameters defined for PostgreSQL
    
    

    JDBC driver identified in the pom.xml

            <!-- The JDBC Driver used by SSP -->
            <jdbc.groupId> </jdbc.groupId>
            <jdbc.artifactId> </jdbc.artifactId>
            <jdbc.version> </jdbc.version>

• ssp-platform-config.properties
  
  • The ssp-platform-config.properties file must be modifed for database connectivity and email settings
    • Original File Location: ./uportal-war/src/main/resources/properties/ssp-platform-config.default.properties
    • Edit the file and save in the SSP_CONFIGDIR
  • Run-Time File Location: <SSP_CONFIGDIR>/ssp-platform-config.properties
    

     

  • Configuration Values:

  Value	Description
  environment.build.hibernate.connection.driver_class	jdbc driver file
  environment.build.hibernate.connection.url	jdbc connection syntax
  environment.build.hibernate.connection.username	jdbc connection database username
  environment.build.hibernate.connection.password	jdbc connection database password
  environment.build.hibernate.dialect	jdbc connection dialect

3.  Build SSP-Platform

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

*** When running a database initialization ant target (initportal, initdb), you need to specify SSP_CONFIGDIR if it isn't already specified as an env var. 

E.g on *nix.... $> SSP_CONFIGDIR=/opt/ssp/sspconfig ant -Dmaven.test.skip=true clean <target> 

Most Common Commands

- Re/Initialize the SSP-Platform database, then run the equivalent of deploy-ear. Destructive! Appropriate for first-time deployments.

  $> SSP_CONFIGDIR=/opt/ssp/sspconfig ant -Dmaven.test.skip=true clean initportal

- Build and deploy entire SSP-Platform portal, including SSP:

  $> SSP_CONFIGDIR=/opt/ssp/sspconfig ant -Dmaven.test.skip=true clean deploy-ear


Other commonly used ant targets:

testdb: Tests the database settings and connectivity

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

deploy-war: Build & deploy _just the SSP-Platform war_ (i.e. not SSP or other portlets, etc.).

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

• Additional step for Microsoft SQL Server to update column types

• Restart Tomcat

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

SSP Demo Data Installation

To install the SSP Demo Data

1. Update SSP & SSP-Platform Source

• Update ssp to either the 'master' branch or the 'rel-1-2-patches' branch depending on your needs for the environment
• Update ssp-platform to either the 'ssp-master' or the 'ssp-rel-1-1-patches' branch

2. Edit the config file

• open 'ssp-config.properties' in your SSP_CONFIGDIR directory 

• edit the line that reads;

  db_liquibase_changelog=classpath:org/jasig/ssp/database/masterChangeLog.xml

  to

  db_liquibase_changelog=classpath:org/jasig/ssp/database/masterChangeLog-demo.xml
  
  

• Save this change

3. Build and Deploy SSP

• Navigate to the SSP source directory and Run the following command to build SSP

  C:\ssp\master> mvn -Dmaven.test.skip=true install

• Navigate to your SSP-Platform source directory and run the following command to deploy SSP

  ant deployPortletApp -DportletApp=(Your SSP source directory)/target/ssp.war

• Stop/Start (or restart) tomcat
• If you watch the catalina.out log file you should see liquibase acquire the changeset and run the changeset for adding demo data. 

4. Import uPortal Userfiles

• Navigate to the SSP-Platform source directory and run the following command to import the uPortal user files so you can login
  
  

  ant -Dmaven.test.skip=true -Ddir=uportal-war/src/main/data/ssp_demo_entities data-import

• You should see a long list of various usernames loaded in with this step

To test this, login as one of the coaches listed on the SSP Demo Data Documentation page and ensure that you can see students and their associated data listed for the coach you login as.

Running the API Integration Tests

Starting with SSP 2.2, the SSP source code distro includes API-level integration tests that can be run against a deployed SSP instance. These tests assume you are deploying SSP to a SSP-Platform instance, i.e. they will not work against a "standalone" SSP implementation. Because of this, the build does not currently use Maven plugins to automatically deploy a SSP binary as part of the integration-test phase. To run the tests, you'll need to manually deploy SSP and SSP-Platform mostly as described above, but with the following changes:

SSP_CONFIGDIR/ssp-config.properties

1. Set: db_liquibase_changelog=classpath:org/jasig/ssp/database/masterChangeLog-apiTest.xml

Then start Tomcat in the usual way. This will initialize the SSP database tables with the data expected by the API tests. At this point, you'll probably want to take a backup of the database so you can quickly restore it to a known good state after each execution of the tests. For Postgres:

$> pg_dump your-database-name > /path/to/backup/of/your-database-name.sql

To run the tests, change into the root of your SSP source code checkout and run:

$> mvn verify -PAPI_INTEGRATION_TEST -PSKIP_SENCHA -DapiPORT=8080 -DapiURL=http://localhost

Or if you need to point to a non-default application instance:

$> mvn verify -PAPI_INTEGRATION_TEST -PSKIP_SENCHA -DapiPORT=8080 -DapiURL=http://some.other.domain.com

Then to reset the db after running the tests, shut down Tomcat and run (Postgres only):

$> dropdb -i your-database-name ; createdb -O sspadmin -E UTF8 your-database-name && psql -U sspadmin -d your-database-name -f /path/to/backup/of/your-database-name.sql

For SQLServer, you should be able to accomplish something similar using the backup and restore features in Microsoft SQL Server Management Studio. Right click on the database and hover over "Tasks".

At this writing, there is a known issue where the Postgres SSP db initialization scripts will sometimes fail, probably due to some sort of collision in a randomization function. This can usually be addressed by rolling back the database and restarting the app server. In some cases, though, the error will persist until the Postgres service is restarted. (Because of the need to rollback SSP-only db initialization, developers often take two database snapshots, one with uPortal-only db artifacts, then another once the SSP db has successfully initialized. This way, if the SSP db fails to initialize, you can reset the db without having to re-run an ant initdb on the uPortal source.)

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