SSP v1.X Developer Installation Instructions

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

Software Prerequisites (JDK, Tomcat, Maven, Ant, RDBMS)
SSP Open Source Project build and deployment
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.6 update 21 or later (JDK 1.7 is not supported as of 2013/01)
- Download Location: http://java.sun.com (openjdk works as well)
- 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/startup, or add an environment variable called CATALINA_OPTS as follows (note on Unix/Linux/OS X you should permanently export the environment variable)
    - On Windows, Edit the file $TOMCAT_HOME\bin\startup.bat and insert or alter the following line, substituting for the desired values. The line you add should go just before the line starting call “%EXECUTABLE%”…:
      set CATALINA_OPTS=-XX:MaxPermSize=300m -Xmx1024m
    - On Linux/Unix/OS X, Edit the file $TOMCAT_HOME/bin/startup.sh and insert the following line, substituting for the desired value, eg. Bash Shell:
      export CATALINA_OPTS="-XX:MaxPermSize=300m -Xmx1024m"
    Symptoms of not including this change
    
    there will be a permGenSpace error 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

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

ALTER DATABASE ssp
 SET ALLOW_SNAPSHOT_ISOLATION ON;
 SET TRANSACTION ISOLATION LEVEL SNAPSHOT
ALTER DATABASE ssp
 SET READ_COMMITTED_SNAPSHOT ON;
 SET TRANSACTION ISOLATION LEVEL READ COMMITTED

For MSSQL 2008 or later:

ALTER DATABASE ssp
 SET ALLOW_SNAPSHOT_ISOLATION ON
ALTER DATABASE ssp
 SET READ_COMMITTED_SNAPSHOT ON
```

RDBMS Platform Flexibility

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

Future support for Oracle and other RDBMS is planned.

Configure and Deploy SSP

The following configurations are required to build and deploy SSP.

1. Create Directories

Prerequisite Installations

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

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.

Git (requires git installation)
The git application can clone the repository to a local repository From the directory created in step 1 above, use a command like the following to clone Clone 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

context.xml

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

Value	Description	Note
system_id	Unique identifier of the SSP instance
db_url	jdbc connection syntax	For Microsoft SQL Server, either specify a port (the default is 1433) or ensure that the SQL Server Browser service is running because the SQL Server JDBC driver defaults to port 1434 which is the SQL Server Server Browser service default port. Depending on the server configuration, either may work, or you may want to explicitly specify the port and instance name, if applicable.
db_driver_class	jdbc database connectivity syntax
db_dialect	Hibernate dialect	Use of one of the `org.jasig.ssp.util.hibernate.ExtendedSQLServer*Dialects` is strongly encouraged if running against SQLSever. The default `ssp-config.properties` has an example.)
db_username	Values for connecting to the SSP database
db_password	Values for connecting to the SSP database
db_admin_username	Values for connecting to the SSP database
db_admin_password	Values for connecting to the SSP database
db_conns_max_active	Values for the database connection pool	The default value will need to be increased for test and product
db_conns_max_idle	Values for the database connection pool	The default value will need to be increased for test and product
db_conns_max_wait	Values for the database connection pool
db_conns_validation_query	Values for the database connection pool
db_liquibase_enabled	Enables the liquibase script for database table management
db_liquibase_changelog	Location for the liquibase change log
db_liquibase_set_mssql_snapshot_isolation	Parameter for configuring a MSSQL database	IMPORTANT The default value is 'true'. Set this value to 'false for MSSQL. The liquibase changeset 000014.xml will be ignored. The sql above configures the database correctly.
smtp_username	Value for email relay
smtp_password	Value for email relay
smtp_host	Value for email relay
smtp_port	Value for email relay
ssp_admins_email_addresses	Recipient of system generated messages
scheduled_coach_sync_enabled	Parameter to enable coach sync process
per_coach_sync_transactions	Parameter to enable the sync process to run per coach instead of one large transaction for all coaches
uportal_session_keep_alive_timeout	Length of time for uPortal sessions KeepAliveFilter
spring.profiles.active	Deployment options	dev-standalone: completely free of uPortal standalone: as the only portlet in a uPortal instance uPortal: as one of many portlets in a uPortal instance

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:

Maven Install Command

C:\ssp\SSP-master>mvn install

Maven Install Command Skipping Tests

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

To build ssp as a developer stand alone environment that does not require uPortal;

Edit $SSP_CONFIGDIR/ssp-config.properties to set it as a standalone environment instead of a uportal environment:

# Spring profiles to activate:  can be comma delimited
# Can choose one of dev-standalone or uportal
spring.profiles.active=dev-standalone
#spring.profiles.active=uportal  <-- this will be uncommented by default

Copy the embedded LDAP file to $SSP_CONFIGDIR so that the user can authenticate:
- Linux/OSX:
```
cp (ssp source folder)/SSP/src/main/config/devExternal/users.ldif $SSP_CONFIGDIR
```

Build the SSP War:

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

Copy the generated war to Tomcat, then restart tomcat (shutdown/startup)
```
cp (ssp source folder)/SSP/target/ssp.war $CATALINA_BASE/webapps
```
- Note: prior to the above step you might need to delete an existing ssp directory and ssp.war file from the tomcat webapps directory if you have previously deployed this portlet.

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.

Git (requires git installation
The git application can clone the repository to a local repository From the directory created in step 1 above, use a command like the following to clone Clone 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

context.xml

server.home=D:/apps/tomcat6

pom.xml (For Microsoft SQL Server with jTDS JDBC driver only)
- JDBC driver for SSP-Platform if not using PostgreSQL
  
  The pom.xml should only be changed with extreme care. The jTDS Microsoft SQL Server jdbc driver needs to be identified in the build. 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
```
        
        <jdbc.groupId>net.sourceforge.jtds</jdbc.groupId>
        <jdbc.artifactId>jtds</jdbc.artifactId>
        <jdbc.version>1.2.4</jdbc.version>
```

local.properties

The local.properties file must be modifed for database connectivity and email settings
File Location: (uPortal-ssp-1-0-0)/filters
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:

Build the full site and database: C:\ssp\uPortal-ssp-1-0-0>ant initportal


Other deployment options:

testdb: Tests the database settings and connectivity

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

Additional step for Microsoft SQL Server to update column types

For Microsoft SQL Server ONLY

Follow steps 2 & 3 from the following page to update appropriate database tables for SSP-PLATFORM

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 Demo Data Documentation page and ensure that you can see students and their associated data listed for the coach you login as.

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