Skip to content

3.0.0 installation

Jump to bottom Edit New page
Gad Krumholz edited this page Mar 18, 2015 · 2 revisions

This is the installation guide for the Vireo an Electronic Thesis and Dissertation Submittal System using a Java / Spring Framework / Play Framework technology stack. This guide covers installing Vireo 3.0.0 in a production level environment and offers several deployment options.

Prerequisites

  1. Java 1.7 or higher

Download Java JDK from Oracle's website. Other Java implementations may work as well.

  1. PostgreSQL 8.4, 9.1 or higher

While other relational databases are supported, these instructions only cover using PostgreSQL. Download and install the latest version of PostgreSQL.

Alternatively you may use other relational databases. Vireo has also been tested on Mysql 5.5, and theoretically should work on any database that is supported by Hibernate. However the developers are not aware of anyone who uses a non-postgresql database or intends to use one in the future.

  1. Play! framework 1.3.x (but not 1.2.x OR 2.x)

Vireo uses the Play! framework, which provides development framework and embedded webserver.

  • Currently, there is an official Play Framework 1.3.0 release here
  • You can also use our forked release from our github for Play1
  • Uncompress the zip file and place in your path. Vireo does not support versions 1.2.x OR 2.x of the Play Framework.

Installation

1) Download

Download Vireo 3.0.0 from our github download page. Next, uncompress the project where you normally deploy web projects from.

2) Database

You need to create a database user for Vireo. If you are using PostgreSQL, you can follow the directions below. Otherwise, consult the documentation for your database for information on how to create users and a database.

// Create the database user Vireo. This will ask you to set a password for the user.
createuser -dSRP vireo

// Create the Vireo database owned by the user Vireo
createdb -U vireo -E UNICODE -h localhost vireo
  • The Schema will get created by hibernate when Vireo starts since jpa.ddl=update by default.

3) Configuration

Next, you need to configure the application. There are many configuration settings that are available to adjust for each install. At a minimum you need to adjust the following in conf/application.conf:

  • Database connectivity:
  • db
  • db.user
  • db.pass
  • Assetstore paths (NOTE: These paths need to be relative to the Vireo application root path):
  • attachments.path
  • index.path
  • deposits.path
  • Mail settings:
  • mail.smtp.host

4) Upgrade

If you are upgrading from a previous version of Vireo you may need to take extra steps to upgrade your data. Follow the upgrade instructions for all the steps between the two versions of Vireo that you are upgrading too.

5) Framework

Next you need to prepare Vireo to be able to run by downloading any dependencies the application has and establishing a secret key for the application. If the play command is not available make sure you have installed the Play framework and added it to your PATH.

// Download library dependencies
play dependencies --sync --clearcache --%test

// Generate a random key
play secret

Deployment Options

There are several different ways you can deploy Vireo into production environments. This section will attempt to give you guidance on the options available and explain how to configure these scenarios.

Play Standalone Webserver (Recommended)

Vireo, built onto the Play Framework, has a stand alone webserver embedded. The included webserver is based upon Netty and has been customized and pre-configured to offer the maximum optimization for play-based applications. For example, Vireo is completely stateless; this means there is no in-memory state persisted between HTTP requests. Using a customized version of Netty allows the standard servlet session handling to be excluded, thus eliminating unneeded resources. There are also customizations to the thread handling in order to better optimize for the asynchronous nature of Vireo.

Vireo stores business critical information; because of this, it is recommended that you always deploy Vireo using SSL. Follow these instructions for configuring SSL certificates on your deployment.

You can use the play command to start and stop the server: // Start Vireo play start [path/to/vireo]

// Stop Vireo
play stop [path/to/vireo]

// Get the PID of the currently running server
play pid [path/to/vireo]

// Tail the logs of the running server
play out [path/to/vireo]

Using Tomcat

Some institutions prefer to deploy Vireo using Tomcat for legacy reasons. You may run into difficulties with long running HTTP requests such as downloading exports. The developers discourage this deployment option; however, it is available if you really, really like using Tomcat.

// Build a Vireo war file
play war vireo -o vireo.war

Deploy the war file into Tomcat's webapp directory. Tomcat must be configured to explode war file deployments. In your server.xml, make sure the appropriate host configuration has unpackWARs set to true. This is the default setting.

Apache Proxy

Some institutions proxy all there application behind a single Apache instance either for load balancing (or Shibboleth - see the next option for that). This may allow you to more easily manage your SSL keys between applications by consolidating them. For an Apache proxy you will need mod_proxy.so (not mod_jk.so).

LoadModule proxy_module modules/mod_proxy.so

…
// This allows Vireo to know where it is being hosted.
ProxyPreserveHost On
ServerName etd.myschool.edu

// Identify where the Vireo application is hosted internally
ProxyPass / http://localhost:9000/
ProxyPassReverse / http://localhost:9000/

If you are using your Apache proxy, or any other proxy, for off loading SSL, and you want to use the auth.forceSSL feature, then you need to take a few extra steps. Because SSL will be handled by the proxy, Play has no way of identifying whether the connection is secure. To solve this problem you need to pass an X-Forward-Proto header that specifies the protocol used.

<VirtualHost *:433>
    RequestHeader set X-Forward-Proto "https"
    
    … Plus the normal Proxy settings shown above ... 

</VirtualHost>

You will also need to edit Vireo's application.conf so that it knows to trust the X-Forward-Proto header from your proxy. Otherwise, anyone could pass that header to Vireo and fake a proxied SSL connection.

// The IP address of the Proxy (to validate X-Forward-* headers)
XForwardSupport = 127.0.0.1

Shibboleth Authentication

Shibboleth is a popular authentication system used in higher education in particular. It allows for users to authenticate themselves with one of several institutions and then securely pass attributes about the user back to the application. For this use case it is ideal for Vireo. Using Shibboleth with Vireo requires that you have proxy through Apache with Shibboleth installed and configured.

  1. Install Shibboleth

Follow the standard installation instructions from the Shibboleth community to install and configure a Service Provider (SP) on your Apache instance.

  1. Apache Proxy

In addition to the normal proxy settings, you will also need to turn Shibboleth on & configure it in Apache. Vireo uses "lazy" authentication, meaning that anonymous users will be able to access the application. When a user either attempts to log in or access a restricted resource, the application will enforce access and redirect the user to initiate Shibboleth authentication. Here is an example Shibboleth configuration for Vireo with the proxy settings included:

  // Configure Shibboleth for "lazy" authentication
  AuthType shibboleth
  ShibURLScheme https
  ShibRequireSessions off
  ShibUseHeaders on
  Require shibboleth

  // Normal Proxy settings (see Apache Proxy above)
  ProxyPreserveHost On
  ServerName etd.myschool.edu
  ProxyPass / http://localhost:9000/
  ProxyPassReverse / http://localhost:9000/
  
  // If using auth.forceSSL (see Apache Proxy above)
  RequestHeader set X-Forward-Proto "https"

  1. Vireo Configuration

    There are several parameters in Vireo's application.conf that you need to review. First you need to decide if Shibboleth will be your only authentication mechanism or if you will allow other options (such as local password-based accounts). Based upon the answer to that question, either turn on or off the appropriate authentication modules, auth.*.enabled = true | false. In addition to an authentication module being enabled or disabled, it may also be visible or invisible. Visible options are shown to the user. Invisible options are not presented to the user, but if someone were to go directly to the appropriate URL, they could still access that authentication option. This may be useful in some scenarios; for now we will assume that Shibboleth is to be both enabled and visible.

Configure shibboleth:

  // Turn Shibboleth on
  auth.shib.enabled = true
  auth.shib.visible = true

  // Brand the Shibboleth authentication option, such as "TAMU NetID"
  auth.shib.name = Shibboleth Authentication
  auth.shib.description = a description of why a user should pick this method…. It may contain HTML.

  // Configure the Shibboleth initiator; for most the default settings are fine.
  auth.shib.login.forceSSL = true
  auth.shib.login.url = /Shibboleth.sso/Login?target=%1s
  auth.shib.logout.url = /Shibboleth.sso/Logout?return=%1s

Next, you need configure how attributes are mapped into Vireo. There are four identity attributes that need to be mapped. First is the NetID; this must be a permanent unique identifier for the user. Shibboleth can be configured to generated targetedIDs which are perfect for this attribute. The NetID is not technically required -- you could fall back to using email addresses to identify users. However, this is problematic because users may often be able to change their email addresses, and when this happens they will lose access to their accounts in Vireo. In addition to NetID, you need a user's First Name, Last Name, and Email Address. Each of these attributes will be provided by Shibboleth via HTTP headers. Provide the name of those headers in Vireo's application.conf, as shown below:

  // Identifying Attribute Mapping
  auth.shib.attribute.netid = SHIB_netid
  auth.shib.attribute.email = SHIB_mail
  auth.shib.attribute.firstName = SHIB_givenName
  auth.shib.attribute.lastName = SHIB_sn

  // Use NetId or Email to uniquely identify a user
  auth.shib.primaryIdentifier = netid

Finally, you should provide as many of the optional attributes as are provided by the Identity Provider. Here is the full set of optional attributes that Vireo is capable of using:

  auth.shib.attribute.institutionalIdentifier = SHIB_uin
  auth.shib.attribute.middleName = SHIB_initials
  auth.shib.attribute.displayName = SHIB_cn
  auth.shib.attribute.birthYear = SHIB_birthYear
  auth.shib.attribute.affiliations = SHIB_eduPersonAffiliation
  auth.shib.attribute.currentPhoneNumber = SHIB_phone
  auth.shib.attribute.currentPostalAddress = SHIB_postal
  auth.shib.attribute.currentEmailAddress = SHIB_mail
  auth.shib.attribute.permanentPhoneNumber = SHIB_permanentPhone
  auth.shib.attribute.permanentPostalAddress = SHIB_permanentPostal
  auth.shib.attribute.permanentEmailAddress = SHIB_permanentEmail
  auth.shib.attribute.currentDegree = SHIB_degree
  auth.shib.attribute.currentDepartment = SHIB_department
  auth.shib.attribute.currentCollege = SHIB_college
  auth.shib.attribute.currentMajor = SHIB_major
  auth.shib.attribute.currentGraduationYear = SHIB_gradYear
  auth.shib.attribute.currentGraduationMonth = SHIB_gradMonth
  auth.shib.attribute.orcid = SHIB_orcid
Add a custom footer
Clone this wiki locally