Page Comparison

...

JDK 1.7 only starting with v2.6.0 (master branch as of 9/1/2014).
- Download Location: http://java.sun.com Download Location: http://java.sun.com Increasingly 1.7 is being hidden, the last known good link is here: JAVA 1.7 If that doesn't work, use the query "java jdk 1.7 download" in a search engine.
- Environment Variable: JAVA_HOME
  Tip
  title 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 2014/04)

Instructions for installing and configuring Tomcat for the SSP-Platform (uPortal 4.0). Last known good link to download Tomcat is here: Tomcat 6.
Warning
title 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.
Code Block
shared.loader=${catalina.base}/shared/classes,${catalina.base}/shared/lib/*.jar
Warning
title 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.
Code Block
<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" emptySessionPath="true"/>
Warning
title 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]

Warning

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

Warning

title	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 LoationLocation: http://maven.apache.org

Environment Variable: MAVEN_HOME

Tip

title	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 Last known good link: Ant Binaries
- Environment Variable: ANT_HOME
  Tip
  title 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, Note: Sencha CMD may not work well, particularly on Linux. If so use this query "SenchaSDKTools-2.0.0-beta3" in a search engine and pick the appropriate version from an alternate download source.
- 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
  
  Tip
  title 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, 2008 R2 or , 2012, 2014
- 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

Code Block

title	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

Code Block
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).):

No Format

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

Info

title	RDBMS Platform Flexibility

Currently SSP supports use of PosgreSQL 9.x and Microsoft SQL Server 2008, or 2008 R2. Starting with 2.5.2, SSP has begun to include patches for SQLServer 2012 compatibility and at least one real-world 2.5.2 6 deployment is running against SQL Server 20122014, although the SSP project team does not officially test against that SQL Server version.

...

Note

title	Prerequisite Installations

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

Create a home project directory for the source project files
- Unix/Linux/Mac example: /usr/local/ssp or /home/ssp or /opt/ssp
- Windows example: C:\ssp
Make the directory only readable by the user that is running Tomcat
Create a directory for the SSP and SSP-Platform config files
- Unix/Linux/Mac example: /usr/local/ssp/ssp-localconfig or /home/ssp/ssp-config or /opt/ssp/ssp-config
- Windows example: C:\ssp\ssp-localconfig
Make the directory readable by the user that is running Tomcat

Set an Environment Variable for the local configuration file location

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

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

Code Block

title	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

Code Block

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

...

${db_username_liquibase} and ${db_username} should be set the same value unless you're on SqlServer, using the JTDS driver, and SSP connects to the database as domain users. If that applies to you, keep ${db_username} set to the unqualified account name, but change ${db_username_liquibase} to the fully-qualified domain account name as shown here. Include the brackets and double back-slashes.

...

default is ${db_username}

...

Examples:

Postgres: public

SQLServer: dbo

...

SQL Server db_url w DOMAIN USER AUTHN may look like this; substitute machine name, instance and domain names w/o <>'s
db_url=jdbc:jtds:sqlserver://<machine_name>:1433/${db_name};instance=<instance_name>;domain=<domain_name>

...

db_liquibase_manage_external_database_by_default

...

True value in external_term.start_date and external_term.end_date will be interpreted in ${db_time_zone_legacy} and re-written in

${db_time_zone_legacy}.

True usually makes sense for both upgrades and fresh installs. Would only set to false if for some reason these fields have already been converted to ${db_time_zone) via some external process.

...

db_batchsize

...

Base Directory for student documents

...

Comma seperated list of subdirectories under student documents

...

Comma separated list of allowable file types that will be used to validate student document files

...

The initial types are pdf,gif,jpg,jpeg,doc,docx,xls,png.

It is important to not include the period/dot in the definition. Only the type abbreviation is required.

...

cacheLifeSpanInMillis

...

This property will dictate how long lived a cache will be only external courses uses a cache

...

Used for migrating persistent timestamps. Prior to work on SSP-1002, SSP-1035, and SSP-1076, timestamps were stored in the JVM default timezone. After that the application assumes they are stored in ${db_time_zone}. In order to correctly migrate existing data, though, the app needs to know the original timezone. This is almost always going to be the current JVM default timezone, hence the default value here, which is a special value instructing the app to lookup and inject that timezone into this config property. In the rare event you need to change that value, you can do so here. This would likely only be necessary if, for whatever reason you change the JVM default *after* the migrations run, which would result in a Liquibase checksum error. To avoid that, just set the relevant timezone here when and if you make that change.

...

JVM-recognized TimeZone ID for the zone in which persistent date/time values should be interpreted. Should rarely if ever need to be overridden. If overridden, should always be set to a TimeZone that does not observe Daylight Savings Time unless trying to cope with legacy data that was stored in a DST-aware TimeZone. Once set, should never be changed else date/time values in the database will be interpreted incorrectly. (SSP does not store timezone data on persistent date/time values and implements no logic for detecting and/or handling changes to this configuration option.)

Default is UTC

...

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

...

Code Block

title	logback.xml

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

...

4. Build SSP

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

Code Block

title	Maven Install Command

C:\ssp\SSP-master>mvn install

Code Block

title	Maven Install Command Skipping Tests

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

Code Block

title	Skips the Sencha Javascript Minification

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

...

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

Code Block

title	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

Code Block

title	context.xml

server.home=D:/apps/tomcat6

...

JDBC driver for SSP-Platform if not using PostgreSQL

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

...

Configuration Values: parameters

...

Code Block

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

...

Original File Location: ./uportal-war/src/main/resources/properties/ssp-platform-config.default.properties
Edit the file and save in the SSP_CONFIGDIR

...

Configuration Values:

...

For best results with SQL Server, the JTDS driver included with the Platform installation is recommended.

...

For best results with SQL Server, the JTDS driver included with the Platform installation is recommended.

...

For best results with SQL Server, the JTDS driver included with the Platform installation is recommended.

...

3. Build SSP-Platform

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

Code Block

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

Warning

title	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

...

To install the SSP Demo Data

1. Update SSP & SSP-Platform Source

Demo data was introduced starting with SSP v1.2.0 and SSP-Platfrom v1.1.0. You'll need to be running those or later versions.

2. Edit the config file

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

edit the line that reads;

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

to

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

Save this change. It will be picked up on the next Tomcat restart. Before doing that, though, if you're on SSP v2.0.1 or later you'll likely need to drop some database constraints in order for the demo data to load. See https://issues.jasig.org/browse/SSP-1877. There is also an open PR that patches the demo data itself as an alternative to manipulating db constraints,If this is a server environment typically the project lives in: /opt/ssp/ (*nix) or C:\ssp (Windows). For most development installs, it's preferable to unzip Tomcat and not install through the source OS package manager. It's easier to configure, clear logs, and start/stop/restart that way. A /etc/init.d/ssp startup script or modification of setenv/startup.sh/bat script is also required before Tomcat starts to add the SSP_CONFIGDIR variable.

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 home project directory created in step 1 above, use a command like the following to clone. A folder SSP will be created.

Code Block

title	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

Code Block

title	context.xml

    <Parameter name="SSP_CONFIGDIR" value="C:/ssp/ssp-config/ssp-config.properties" />

ssp-config.properties
- The ssp-config.properties file must be modifed for database connectivity and email settings
- File Location: src/main/config/external
- Action: copy the ssp-config.properties file to the local configuration directory SSP_CONFIGDIR. (ie: C:\ssp\ssp-config or \home\ssp\ssp-config)
- NOTE: There are more configuration values then present here. It's always a good idea to take the default config file copy to SSP_CONFIGDIR and make changes there
- Configuration Values:

Value	Description	Note
system_id	Unique identifier of the SSP instance	For server installs this is useful in identifying log files. DEV1 or other unique name is the idea.
db_username	Values for connecting to the SSP database	The username setup in the RDBMS section above. Usually "ssp".
db_password	Values for connecting to the SSP database	The password setup in the RDBMS section above for the ssp user.
db_admin_username	Values for connecting to the SSP database	The db_admin username you setup in the RDBMS section above. Usually "sspadmin".
db_admin_password	Values for connecting to the SSP database	The password setup in the RDBMS section above for sspadmin.
db_username_liquibase	Value to allow for MS SQL Server domain accounts	${db_username_liquibase} and ${db_username} should be set the same value unless you're on SqlServer, using the JTDS driver, and SSP connects to the database as domain users. If that applies to you, keep ${db_username} set to the unqualified account name, but change ${db_username_liquibase} to the fully-qualified domain account name as shown here. Include the brackets and double back-slashes. db_username_liquibase=[DOMAIN\\username] default is ${db_username} Examples should be in the default ssp-config.properties file.
db_schema	Db schema for the SSP database	Examples: Postgres: public SQLServer: dbo
db_name	Value for the SSP database	The database name configured above in the RDBMS section. Normally "ssp".
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. SQL Server db_url w DOMAIN USER AUTHN may look like this; substitute machine name, instance and domain names w/o <>'s db_url=jdbc:jtds:sqlserver://<machine_name>:1433/${db_name};instance=<instance_name>;domain=<domain_name>
db_driver_class	jdbc database connectivity syntax	class=org.postgresql.Driver or net.sourceforge.jtds.jdbc.Driver or com.microsoft.sqlserver.jdbc.SQLServerDriver
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.) Usually org.jasig.ssp.util.hibernate.ExtendedSQLServer2008Dialect for SQL Server and org.hibernate.dialect.PostgreSQLDialect for Postgres.
db_conns_max_active	Values for the database connection pool	The default value will need to be increased for dev/test/alpha and production servers
db_conns_max_idle	Values for the database connection pool	The default value will need to be increased for dev/test/alpha and production servers
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	Should be set to true
db_liquibase_changelog	Location for the liquibase change log	Normally you use this: org/jasig/ssp/database/masterChangeLog.xml but if you want to load "test" data you can run this: org/jasig/ssp/database/masterChangeLog-apiTest.xml after starting once with that changelog you can shutdown Tomcat and change it back if desired.
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.* You will get a seemingly unrecoverable error if run in later MSSQL versions!.
db_liquibase_strip_journal_comment_markup	Parameter to enable a script to convert HTML Journal Entries to plain text
db_liquibase_strip_tuition_paid_is_y	True value will delete the existing values forced into the database in v1.2.0, False will leave the existing values alone	This only applies to implementers who installed v1.2.0 or earlier AND populated the external_registration_status_by_term.tuition_paid field with external data
db_liquibase_manage_external_database_by_default	True value will allow SSP to manage the tables and views	If you want to take total control of SSP's external views and tables, change that property to false in your SSP_CONFIGDIR/ssp-config.properties **before first startup! And once you've started up, there's really no point in ever changing that value afterwards. (If you turn it off, then decide you want SSP to manage external views and tables after all, you'll need to update config set value = 'true' where name = 'manage_integration_database' and then restart.) This is an implementation decision that should not be taken lightly as clients would have to manage the external_data views themselves when upgrading if any external_data changes are made. For that reason there are no institutions currently using this and for all demo/dev/test environments leave this to false.
db_liquibase_convert_external_term_timestamps	True value in external_term.start_date and external_term.end_date will be interpreted in ${db_time_zone_legacy} and re-written in ${db_time_zone_legacy}.	True usually makes sense for both upgrades and fresh installs. Would only set to false if for some reason these fields have already been converted to ${db_time_zone) via some external process.
db_batchsize	The number of records to process for database transactions.	The default value is 300. Use of the parameter can increase performance of queries writing large sums of data into the database. This is primarily used in the Caseload Re-assignment tool.
student_documents_base_dir	Base Directory for storing student documents	It is important to not end in path separator like / or \. This can be a network mount, but the folder must be found in Tomcat or by Tomcat such that it can store files and serve them statically. Typically this involves setting up a folder and symbolically linking to a network storage medium. (The same thing is done with student photos).
student_documents_volumes	Comma separated list of subdirectories under student documents	The first file loaded after server start goes into vol1, second into vol2, etc. This facilitates the 'file sharding' effort to distribute files among multiple volumes to decrease any sort of maintenance of these files. It is important to not end in path separator like / or \.
student_documents_file_types	Comma separated list of allowable file types that will be used to validate student document files	The initial types are pdf,gif,jpg,jpeg,doc,docx,xls,png. It is important to not include the period/dot in the definition. Only the type abbreviation is required.
student_documents_max_size	Maximum size of an individual file, in bytes	The default value is 5000000
cacheLifeSpanInMillis	This property will dictate how long lived a cache will be. Only external courses uses a cache	default is 86400000 = 1 day
db_time_zone_legacy	Parameter to set the timezone for data migration	Used for migrating persistent timestamps. Prior to work on SSP-1002, SSP-1035, and SSP-1076, timestamps were stored in the JVM default timezone. After that the application assumes they are stored in ${db_time_zone}. In order to correctly migrate existing data, though, the app needs to know the original timezone. This is almost always going to be the current JVM default timezone, hence the default value here, which is a special value instructing the app to lookup and inject that timezone into this config property. In the rare event you need to change that value, you can do so here. This would likely only be necessary if, for whatever reason you change the JVM default after the migrations run, which would result in a Liquibase checksum error. To avoid that, just set the relevant timezone here when and if you make that change. Default is CURRENT_JVM_DEFAULT Note: In the past there has been problems with DST on the East Coast make sure the JVM is set to New York time.
db_time_zone	Timezone ID for the JVM	JVM-recognized TimeZone ID for the zone in which persistent date/time values should be interpreted. Should rarely if ever need to be overridden. If overridden, should always be set to a TimeZone that does not observe Daylight Savings Time unless trying to cope with legacy data that was stored in a DST-aware TimeZone. Once set, should never be changed else date/time values in the database will be interpreted incorrectly. (SSP does not store timezone data on persistent date/time values and implements no logic for detecting and/or handling changes to this configuration option.) Default and normal value is UTC
highly_trusted_ips	The list of IP addresses that are allowed to access the APIs	This is used in conjunction with high_trusted_ips_enabled in the System Configuration options in SSP -> Admin view.
smtp_username	Value for email relay
smtp_password	Value for email relay
smtp_host	Value for email relay	For development purposes many use localhost
smtp_port	Value for email relay	Default is 25
smtp_protocol	Protocol for email	Default is smtp

logback.xml

The logback.xml controls the log location and level
File Location: src/main/config/external
Action: copy the logback.xml file to the local configuration directory SSP_CONFIGIDR (ie: C:\ssp\ssp-config or /home/ssp/ssp-config)
Configuration Values: property file

Code Block

title	logback.xml

<property file="C:/ssp/ssp-config/logback.xml"

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

Common loggers used in past development have been:

Code Block

title	Common loggers

<logger name="org.jasig.ssp.service.external.impl.ExternalPersonServiceImpl" level="debug" />


 <!-- Turns on ExternalPersonSync task logging which by default runs at 1a.m. and does magic of updating person records from records -->
<logger name="org.jasig.ssp.service.external.impl.ExternalPersonSyncTaskImpl" level="trace" />     
 
<!-- Turns off Coach Sync logging which can be mundane -->
<logger name="timing.org.jasig.ssp.service.impl.PersonServiceImpl" level="error" />  
                 
<logger name="org.jasig.ssp.service.impl.MapStatusReportCalcTaskImpl" level="debug" />
 
<!-- Turns off some Email errors which can be annoying if there is no SMTP server spun up-->
<logger name="org.jasig.ssp.service.impl.MessageServiceImpl" level="error" />

4. Build SSP

Use the following command to build the SSP-Open-Source-Project and install it in the local Maven repository (use quotes "-Dmaven.test.skip=true" for Windows):

Code Block

title	Maven Install Command

C:\ssp\SSP\mvn clean -e -U -Dmaven.test.skip=true install

Code Block

title	Skips the Sencha Javascript Minification

C:\ssp\SSP\mvn -PSKIP_SENCHA -Dmaven.test.skip=true clean -e -U install

...

Anchor
SSP-Platform Build
SSP-Platform Build
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. You will have a directory called uPortal when done.

Code Block

title	Clone Source Files

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

2. Modify SSP-Platform Configuration Files

build.properties
- The build.properties.sample file is copied or renamed in the SSP-Platform directory. The server.home parameter defines the location of Tomcat (TOMCAT_HOME) and must be configured.
- File Location: (uPortal/ or SSP-Platform/)
- Configuration Values: server.home parameter

Code Block

title	context.xml

server.home=C:/ssp/tomcat

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

Warning
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/ or SSP-Platform/)
Configuration Values: parameters

Action: modify the exist parameters defined for SQL Server

Code Block

title	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: <SSP_PLATFORM_DIR>/uportal-war/src/main/resources/properties/ssp-platform-config.default.properties
- Edit the file and save in the SSP_CONFIGDIR make sure to remove the "default" so it's named: "ssp-platform-config.properties"
Run-Time File Location: <SSP_CONFIGDIR>/ssp-platform-config.properties

Configuration Values: NOTE: There are more values in the file than listed here. It's always a good idea to copy the file to SSP_CONFIGDIR, rename and then make modifications as necessary there.

Value	Description
environment.build.hibernate.connection.driver_class	jdbc driver file (See ssp-config.properties, this uses the same value) For best results with SQL Server, the JTDS driver included with the Platform installation is recommended.
environment.build.hibernate.connection.url	jdbc connection syntax (See ssp-config.properties, this uses the same value) For best results with SQL Server, the JTDS driver included with the Platform installation is recommended.
environment.build.hibernate.connection.username	jdbc connection database username (See ssp-config.properties, this uses the same value)
environment.build.hibernate.connection.password	jdbc connection database password (See ssp-config.properties, this uses the same value)
environment.build.hibernate.dialect	jdbc connection dialect (See ssp-config.properties, this uses the same value) For best results with SQL Server, the JTDS driver included with the Platform installation is recommended.
environment.build.uportal.server	Hostname and port for your SSP deployment. (Default: localhost:8080)
environment.build.uportal.protocol	HTTP/S protocol at which end users access your SSP deployment. (Default: http) (All production should be https!)
environment.build.uportal.email.fromAddress	Address from which Platform email will originate. Rarely used. (Default: ssp@university.edu)
environment.build.sso.*	Several properties which configure inbound LTI and legacy SSO. See documentation specific to those features: SSP LTI Provider and SSP Signed URL SSO. Note that to enable these features `environment.build.sso.local.sharedSecret` must be set to the same non-empty value as `ssp_platform_sso_ticket_service_shared_secret` in `$SSP_CONFIGDIR/ssp-config.properties`
(database specific attributes)	(default values)
environment.build.raweventsdb.connection.driver_class	${environment.build.hibernate.connection.driver_class}
environment.build.raweventsdb.connection.url	${environment.build.hibernate.connection.url}
environment.build.raweventsdb.connection.username	${environment.build.hibernate.connection.username}
environment.build.raweventsdb.connection.password	${environment.build.hibernate.connection.password}
environment.build.aggreventsdb.connection.driver_class	${environment.build.hibernate.connection.driver_class}
environment.build.aggreventsdb.connection.url	${environment.build.hibernate.connection.url}
environment.build.aggreventsdb.connection.username	${environment.build.hibernate.connection.username}
environment.build.aggreventsdb.connection.password	${environment.build.hibernate.connection.password}
environment.build.portaldb.initial.size	1
environment.build.portaldb.min.idle	1
environment.build.portaldb.max.active	50
environment.build.portaldb.max.idle	50
environment.build.portaldb.max.wait	2000
environment.build.portaldb.abandon.when.percentage.full	70
environment.build.portaldb.remove.abandoned	TRUE
environment.build.portaldb.remove.abandoned.timeout	300
environment.build.portaldb.jdbc.interceptors	ConnectionState(useEquals=true);ResetAbandonedTimer
environment.build.portaldb.test.while.idle	TRUE
environment.build.portaldb.test.on.borrow	TRUE
environment.build.raweventsdb.initial.size	1
environment.build.raweventsdb.min.idle	1
environment.build.raweventsdb.max.active	50
environment.build.raweventsdb.max.idle	50
environment.build.raweventsdb.max.wait	2000
environment.build.raweventsdb.abandon.when.percentage.full	70
environment.build.raweventsdb.remove.abandoned	TRUE
environment.build.raweventsdb.remove.abandoned.timeout	300
environment.build.raweventsdb.jdbc.interceptors	ConnectionState(useEquals=true);ResetAbandonedTimer
environment.build.raweventsdb.test.while.idle	TRUE
environment.build.raweventsdb.test.on.borrow	TRUE
environment.build.aggreventsdb.initial.size	1
environment.build.aggreventsdb.min.idle	1
environment.build.aggreventsdb.max.active	50
environment.build.aggreventsdb.max.idle	50
environment.build.aggreventsdb.max.wait	2000
environment.build.aggreventsdb.abandon.when.percentage.full	70
environment.build.aggreventsdb.remove.abandoned	TRUE
environment.build.aggreventsdb.remove.abandoned.timeout	300
environment.build.aggreventsdb.jdbc.interceptors	ConnectionState(useEquals=true);ResetAbandonedTimer
environment.build.aggreventsdb.test.while.idle	TRUE
environment.build.aggreventsdb.test.on.borrow	TRUE

3. Build SSP-Platform

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

Code Block

*** 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> 
   or 
export SSP_CONFIGDIR=/opt/ssp/sspconfig ; ant -Dmaven.test.skip=true clean <target> 

-----------
Most Common Commands

- Initialize the SSP-Platform database, then runs deploy-ear. (Basically initdb + deploy-ear) *Destructive!* Appropriate for first-time deployments only.

  $> ant -Dmaven.test.skip=true clean initportal

- To Build and deploy the entire SSP-Platform portal and the SSP war to Tomcat (most commonly used since initportal is only used once):

  $> 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). *Destructive if database isn't empty/new!*

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
  
   $> ant -Dmaven.test.skip=true deployPortletApp -DportletApp=../SSP/target/ssp.war

Additional step for Microsoft SQL Server to update column types

Warning

title	For Microsoft SQL Server ONLY

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

Restart Tomcat (../tomcat/bin/shutdown.sh ... ../tomcat/bin/startup.sh OR /etc/init.d/ssp/restart OR windows service tomcat restart)

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

...

Anchor
ssp-demo-data
ssp-demo-data
SSP Demo Data Installation

To install the SSP Demo Data

1. Update SSP & SSP-Platform Source

Demo data was introduced starting with SSP v1.2.0 and SSP-Platfrom v1.1.0. You'll need to be running those or later versions.

2. Edit the config file

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

edit the line that reads;

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

to

Code Block
db_liquibase_changelog=classpath:org/jasig/ssp/database/masterChangeLog-apiTest.xml

Warning

title	Demo Data

The "masterChangeLog-demo.xml" is old and not supported post SSP 2.2.0. Use the above masterChangeLog-apiTest.xml (which is also older but more up to date) or the ssp-training data at https://github.com/Jasig/ssp-training for the most up to date demo, training, and CI data.

If you must use masterChangeLog-demo data see this:

Before re-building and restarting Tomact, if you're on SSP v2.0.1 or later you'll likely need to drop some database constraints in order for the demo data to load. See
https://issues.jasig.org/browse/SSP-1877. There is also an open PR that patches the demo data itself as an alternative to manipulating db constraints
Rebuild SSP and Deploy Portlet as below.

Navigate to the SSP-Platform source directory and run the following command to import the uPortal user files so you can login
Code Block
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.

Save this change. It will be picked up on the next Tomcat restart.
3. Build and Deploy SSP

Navigate to the SSP source directory and Run the following command to build SSP
Code Block
C:\ssp\master>SSP mvn clean -Dmaven.test.skip=true -e -U install
Navigate to your SSP-Platform source directory and run the following command to deploy SSP
Code Block
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

...

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

...

, localhost.log, and/or stderr.log/stdout.log log file(s) depending on the Tomact instance, you should see liquibase acquire the changeset and run the changeset for adding the demo data.

To test this, login as admin, admin or coach1, password0 and ensure that you can see students and their associated data listed for the coach you login as.

...

Running the API Integration Tests

...

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

Versions Compared

Old Version 35

New Version Current

Key

2. Clone the SSP Open Source Project repository from GitHub

3. Modify SSP Configuration Files

4. Build SSP

1. Clone the SSP-Platform repository from GitHub

2. Modify SSP-Platform Configuration Files

3. Build SSP-Platform

4. Test Deployment

1. Update SSP & SSP-Platform Source

2. Edit the config file

2. Clone the SSP Open Source Project repository from GitHub

3. Modify SSP Configuration Files

4. Build SSP

Anchor
SSP-Platform Build
SSP-Platform Build
Configure and Deploy SSP-Platform

1. Clone the SSP-Platform repository from GitHub

2. Modify SSP-Platform Configuration Files

3. Build SSP-Platform

4. Test Deployment

Anchor
ssp-demo-data
ssp-demo-data
SSP Demo Data Installation

1. Update SSP & SSP-Platform Source

2. Edit the config file

4. Import uPortal Userfiles

Running the API Integration Tests

Page Comparison

Versions Compared

Old Version 35

New Version Current

Key

2. Clone the SSP Open Source Project repository from GitHub

3. Modify SSP Configuration Files

4. Build SSP

1. Clone the SSP-Platform repository from GitHub

2. Modify SSP-Platform Configuration Files

3. Build SSP-Platform

4. Test Deployment

1. Update SSP & SSP-Platform Source

2. Edit the config file

2. Clone the SSP Open Source Project repository from GitHub

3. Modify SSP Configuration Files

4. Build SSP

AnchorSSP-Platform BuildSSP-Platform BuildConfigure and Deploy SSP-Platform

1. Clone the SSP-Platform repository from GitHub

2. Modify SSP-Platform Configuration Files

3. Build SSP-Platform

4. Test Deployment

Anchorssp-demo-datassp-demo-dataSSP Demo Data Installation

1. Update SSP & SSP-Platform Source

2. Edit the config file

4. Import uPortal Userfiles

Running the API Integration Tests

Anchor
SSP-Platform Build
SSP-Platform Build
Configure and Deploy SSP-Platform

Anchor
ssp-demo-data
ssp-demo-data
SSP Demo Data Installation