-
Notifications
You must be signed in to change notification settings - Fork 34
2.0.0 Install
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 1.8 in a production level environment and offers several deployment options.
- Java 1.5 or higher
Download Java JDK from Oracle's website. Other Java implementations may work as well.
- 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.
- Python 2.4 or higher
Most operating systems have python pre-installed. If not, please download and install Python 2.4 or higher.
- Play! framework 1.2.5 (but not 2.x)
Vireo uses the Play! framework, which provides development framework and embedded webserver. Download and install Play 1.2.5. Uncompress the zip file and place in your path. Vireo does not yet support version 2.x of the Play Framework but we hope to migrate to this version in the future.
*Play 1.2.5 has a bug that does not delete temporary files. There is a bash script sitting in the Vireo's root directory (clean-temp.sh) that your system admin can use with a cron job to clear out the temporary files.
Download Vireo 1.8 from our github download page. Next, uncompress the project where you normally deploy web projects from.
wget (https://github.com/TexasDigitalLibrary/Vireo/downloads/vireo-1.8.zip) vireo-1.8.zip
unzip vireo-1.8.zip
You need to create a database user and establish the schema 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. Schemas for additional databases are available in [vireo]/conf/sql/[database]/schema.sql.
// 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
// Create the schema & indexes
psql -U vireo vireo < [vireo]/conf/sql/postgresql/schema.sql
psql -U vireo vireo < [vireo]/conf/sql/postgresql/indexes.sql
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:
attachments.path,index.path,deposits.path -
Mail settings:
mail.smtp.host,mail.from,mail.replyto
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 version of Vireo that you are upgrading too.
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 deps --sync
// Generate a random key
play secret
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.
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]
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.
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 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.
- Install Shibboleth
Follow the standard installation instructions from the Shibboleth community to install and configure a Service Provider (SP) on your Apache instance.
- 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"
-
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,
auto.*.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