SSP v1.1.1 Installation Instructions

Step by step instructions for building and deploying the SSP 1.1.1 release.

1. Software Prerequisites (JDK, Tomcat, Maven, Ant, RDBMS)
2. 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

  • 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

• 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

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 MyDatabase
 SET ALLOW_SNAPSHOT_ISOLATION ON
ALTER DATABASE MyDatabase
 SET READ_COMMITTED_SNAPSHOT ON

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.

2. SSP Configuration Files

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

    • 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)

• ssp-config.properties
  
  • The ssp-config.properties file must be modifed for database connectivity and email settings
  • File Location: github

  • Action: create the  ssp-config.properties file in 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_name	Value for 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
    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: github

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

• Configuration Values: property file
  
  

<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

3. 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 (For Microsoft SQL  only)
  

  • JDBC driver for SSP-Platform if not using PostgreSQL

    The pom.xml should only be changed with extreme care.  The 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 existing parameters defined for PostgreSQL
    
    

    JDBC driver identified in the pom.xml

            <!-- The JDBC Driver used by SSP -->
            <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

4.  Build SSP-Platform

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

Build the full site and database by running 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 deploPortletApp -DportletApp=..\SSP-Open-Source-Project/target/ssp.war)

• Additional step for Microsoft SQL Server to update column types

• Restart Tomcat

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

6. Production Deployment Tips

• Delete Demo Users

  You should delete or change the passwords for the uPortal users created for demonstration purposes, especially in a production deployment. This can be done through the user interface: Manage Users ->  Find an Existing User -> [Enter user ID from list below] -> [Click result] -> Delete or Edit, then change password. Demo users:

  • advisor0
  • ken
  • student0
  • student1

  Non-private installs should also either change the admin user's password or add some other user to the Portal Administrators group and delete the admin user.

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