Released on July 10, 2014
For all existing installations of 2.0.X and 2.1.X, important upgrade instructions exist in the previous 2.1, 2.2, 2.3 and 2.4 Release notes.
If you are running a SSP version prior to 1.1.1, you are strongly encouraged to upgrade or otherwise apply the reporting subsystem security patches described by SSP-701. If you are running SSP version 2.0.0 or 2.0.0-b3, you are strongly encouraged to upgrade to 2.0.1 or 2.1.0 or 2.2.0 or later or otherwise apply the Confidentiality Level-related patches for the Student Documents tool as described by SSP-1917. All implementers of this release should consider installing the patches listed in the commit section of the SSP-2721 issue details. Also please take a few minutes to review additional security-related announcements detailed at the top of the SSP space here in Confluence. |
The following software prerequisites must be installed with the appropriate environment variables to build and run SSP:
Environment Variable: JAVA_HOME
JAVA_HOME=/path/to/your/java (ie: /usr/local/java or C:\java\jdk)
|
Instructions for installing and configuring Tomcat for the SSP-Platform (uPortal 4.0)
It is important to complete sections: Environment Variables, Shared Libraries, Shared Sessions, Java Heap. Minimally, the catalina.properties file must contain:
shared.loader=${catalina.base}/shared/lib/*.jar |
Additionally, a performance improvement has been experienced by enabling compression in Tomcat
Add compression="force" to the server.xml in the connector like the following:
<Connector port="8080" protocol="HTTP/1.1 connectionTimeout="20000" redirectPort="8443" emptySessionPath="true" compression="force" /> |
Environment Variable: MAVEN_HOME
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)
Blacklist several known-bad repos. If you don't already have a ~/.m2/settings.xml, use the following:
|
Download Location: http://ant.apache.org
Environment Variable: ANT_HOME
ANT_HOME= /path/to/your/ant (ie: /usr/local/ant or C:\tools\ant) |
Download Location: http://www.sencha.com/products/sdk-tools/download
PATH= append the root to the path statement |
See SSP Sencha Build Tool Usage for additional installation steps on 64-bit OSs
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
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 MyDatabase SET ALLOW_SNAPSHOT_ISOLATION ON ALTER DATABASE MyDatabase SET READ_COMMITTED_SNAPSHOT ON |
Currently SSP supports use of PosgreSQL and Microsoft SQL Server 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. |
The following configurations are required to build and deploy SSP-Platform.
| Zip Download |
|---|
The source files can be downloaded in a zip file
|
In order to build SSP-Platform directly from the Github repository, follow the developer environment instructions. The requisite software and configurations are similar but add the git component to maintain a local repository.
|
Windows example: C:\ssp\ssp-local
Make the directory only readable by the user that is running Tomcat
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) |
Action: Copy the baseline ssp-config.properties file into the local configuration directory created above and rename it to ssp-config.properties. Or start with an empty ssp-config.properties in that directory and add only the properties for which you need to override the default value.
Configuration Values:
| Value | Description | Note |
|---|---|---|
| system_id | Unique identifier of the SSP instance | |
| 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_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} |
| db_schema | Db schema for the SSP database | Examples: Postgres: public SQLServer: dbo |
| db_name | Value for the SSP database | |
| 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. For best results with SQL Server, the JTDS driver included with the Platform installation is recommended. Examples of the url are provided in the sample ssp-config.properties file.
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 | For best results with SQL Server, the JTDS driver included with the Platform installation is recommended. Examples of the class are provided in the sample ssp-config.properties file. |
| 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_conns_max_active | Values for the database connection pool | The default value will need to be increased for test and production |
| db_conns_max_idle | Values for the database connection pool | The default value will need to be increased for test and production |
| 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. |
| 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_external_fa_not_null_drop_y | True value allows the table to be re-created with the correct column definitions for null values | |
| db_liquibase_external_apply_natural_keys | True value will apply the new primary keys to the external database | Version 2.0.0 added primary keys to the external database tables for performance and uniqueness enhancements. If there are non-unique values in the database, the liquibase will fail to make the table changes. |
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.) |
| 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 student documents | The default is ${catalina.base}/ssp-uploads/student-docs It is important to not end in path separator like / or \ |
| student_documents_volumes | Comma seperated list of subdirectories under student documents | 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 |
| 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 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 |
| smtp_username | Value for email relay | |
| smtp_password | Value for email relay | |
| smtp_host | Value for email relay | |
| smtp_port | Value for email relay | |
| smtp_protocol | Protocol for email | Default is smtp |
| 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 | |
scheduled_task_cleanup_wait_millis | Max amount of time, in milliseconds, the app will wait during shutdown for any background tasks to abandon their work. | Default is 10000 |
| uportal_session_keep_alive_timeout | Length of time for uPortal sessions KeepAliveFilter | |
| oauth2_client_password_encoding_secret | Config for setting the key with which OAuth2 Client secrets are hashed before being placed into the database | |
| spring.profiles.active | Deployment options |
|
ssp_main_use_minifed_js | Parameter to determine the javascript file used in the deployment | When set to true, ssp-main.jsp will include a minified js called app-all.js When set to false, ssp-main.jsp will include the non-minified app.js |
ssp_trusted_code_run_as_key | When the scheduled jobs run they have to "run as" a particular user. SSP uses SpringSecurity for this, and the application code is allowed to sudo to a different user as long as it knows the special shared secret defined in the configuration. | Default is SZP. If you plan on running deployment-specific third-party code, or really even other webapps in the same Tomcat contains, you should probably select a more complex, deployment-specific value. |
logback.xml
Action: Copy the baseline logback.xml file into the local configuration directory created above
ssp-config.properties file you configured above. E.g.:<property file="C:/ssp/ssp-local/ssp-config.properties" /> |
<platform-src-dir>/build.properties.samplebuild.properties.server.home to the path below which your Tomcat webapps directory is located.server.home=C:/path/to/your/tomcat/install |
Configuration Values:
| Value | Description |
|---|---|
| environment.build.hibernate.connection.driver_class | jdbc driver file For best results with SQL Server, the JTDS driver included with the Platform installation is recommended. |
| environment.build.hibernate.connection.url | jdbc connection syntax 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 |
| environment.build.hibernate.connection.password | jdbc connection database password |
| environment.build.hibernate.dialect | jdbc connection dialect For best results with SQL Server, the JTDS driver included with the Platform installation is recommended. |
Don't forget this step. Without it, you'll experience seemingly random timeout error messages when trying to access the SSP portlet. |
<timeout>120</timeout> to <timeout>20000</timeout>
*** 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 - Build entire uPortal (incl. all wars), deploy entire uPortal, ant deploy-ear - Build the full site and database, ant initportal (Warning- this will reset the entire uPortal database) 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-war: Build & deploy _just the uPortal war_ (i.e. not portlets, etc.). deployPortletApp: Deploy one (already-built) portlet war file to Tomcat (example ant deploPortletApp -DportletApp=..\SSP-Open-Source-Project/target/ssp.war) |
This command will download the |
Follow steps 2 & 3 from the following page to update appropriate database tables for SSP-PLATFORM |
http://localhost:8080/ssp-platform
If you are deploying to a production environment, you should delete or change the passwords for the uPortal users created for demonstration purposes, including the
|
If anything in it is incorrect or unclear, please leave a comment below.