2.0.0 Configuration

The main application configuration for Vireo is located in conf/application.conf. The file consists of simple name/value pairs used to direct how the application operates. Oftentimes it is helpful to have several deployment scenarios defined in a configuration file at the same time. To support this, Play has the concept of frameworks. Each framework is an ID used to identify a configuration set. All the parameters defined below can be scoped to a particular framework. For example:

paramater1 = default value
%myframework.paramater1 = another value

When evaluated if Play is operating under the framework "myframework" then paramater1 is "another value". However, under any other framework the value is "default value". Using this you can specify local deployment configuration. For example, if you want to change the HTTP port that is used for your instance of Vireo, you could define %myedu.http.port = 80. Then, when you run Play, always use the "myedu" framework.

To specify a framework when running Vireo add --%frameworkID to the end of any command. For example play start --%myedu

HTTP

• http.port = 9000

  The HTTP port Vireo will listen on when using the built-in web server.

• http.path = /

  The path where Vireo will be mounted when using the built-in web server. The default is at "/" the root of the webserver. However, if you will be running multiple applications on this host, then you will want to scope Vireo to a particular path, such as "/vireo". Tip: always start with a slash, but never have a trailing slash after the path.

• http.address = *

  Configure the IP address that the built-in webserver should listen on. By default the webserver will listen on all addresses.

• application.baseUrl

  This is used to identify where Vireo is installed on for background tasks. Normally when resolving all links, Vireo will look at the current HTTP request to determine where the application is hosted. However sometimes Vireo needs to resolve URLs back to the application (like sending emails in the background); in these cases this parameter will be used. If you are proxying Vireo through Apache you will still need to use "PreserveHost On".

Database

• db

• db.user

• db.pass

  Configure the database data source. Vireo works with either postgresql, mysql, or the built-in H2 database. The "db" parameter needs to be the JDBC url identifying the database host and database name. For example to connect to a postgresql database the url would look like: "postgresql://host/database_name". Then use the db.user and db.pass to provide credentials for authenticating with the database. It is not recommended that you embed the username & password in the url because it is displayed as clear text in Vireo's system control panel.

• db.pool.timeout = 1000

• db.pool.maxSize = 30

• db.pool.minSize = 10

  Configure how database connections are pooled between web requests.

• jpa.ddl = create

  Configure the JPA database schema lifecycle. The possible values for this parameter are listed below. For production installs it is highly recommended that you use the "validate" setting, forcing you to manually install any schema modifications.

  • validate: validate the schema, makes no changes to the database
  • update: update the schema
  • create: creates the schema, destroying previous data
  • create-drop: drop the schema at the end of the session

• jpa.debugSQL = false

  Turn this option on (and set your log level to DEBUG) to see the SQL statements that are being generated by Vireo.

• jpa.dialect = org.tdl.vireo.model.jpa.TableNameSequencePostgresDialect

  This option only needs to be turned on when you are using a PostgreSQL database. Using this specific dialect creates a sequence id for each object type in Vireo. Each object in Vireo has a unique ID (ie. Submission #123). These ids are generated from a sequence, by default the PostgreSQL hibernate implementation uses one id sequence shared across all objects. This looks weird to users as they see the submission numbers jump by bunches because the intervening ids were used by other objects. Using this object makes the submission IDs look more predictable as they will increment one at a time without skipping any.

Assetstore

• attachments.path = data/attachments

  The location where all file attachments will be stored. This directory may be of substantial size. The directory will consist of four levels of 256 hash directories. At the leaf nodes of these sub directories these are the individual files stored according to their UUID name. This directory must be backed up regularly.

• index.path = data/indexes

  This is where the Lucene search indexes are stored. Do not mount this directory over NFS because it may result in locking issues. It would be best if this directory were mounted on a local disk. The data stored in this directory may be rebuilt at any time from the database. To rebuild the search index, use the controls under the System Control Panel.

• deposits.path = data/deposits

  If the file based depositor is used then all deposits will be restricted to this directory. You can turn this feature off in the spring-based application-context.xml configuration.

Mail

• mail.smtp.host = 127.0.0.1

• mail.smtp.user

• mail.smtp.pass

• mail.smtp.channel

  The SMTP mail host where email from Vireo should be routed. You may authenticate with a username & password and optionally use SSL for the connection.

• mail.from

• mail.replyto

  These are the default from and replyto addresses used for all emails generated from Vireo. These parameters are required.

Authentication

Vireo has a pluggable authentication module with (at the time of the current writing) two implementations. You can use local accounts with Vireo where a password is stored in the local database, or you can configure Vireo to use external authentication via Shibboleth. The recommended route is to integrate Vireo with your campus directory using Shibboleth. This will allow you to pull attributes such as the student's official name, contact information, permanent address, etc. directly from the central directory.

Each module can be either enabled or disabled; in addition, it can be visible or invisible. A disabled module cannot be used for authentication, period. However, if a module is enabled, it may be invisible, meaning that it can be used for authentication but will not be presented as an option for users. The only way it can be accessed, if it is invisible, is by directly accessing the authentication URL: /login/[module-name]. This can be convenient when you want students to authenticate via Shibboleth but allow a system administrator to directly access the system with a local account.

You may also have multiple enabled and visible authentication modules. When this case occurs, each user will be asked to select which method they want to authenticate with.

• auth.forceSSL = false

  If this option is enabled then all authenticated sessions will be forced to SSL regardless of the authentication method used. If a user attempts to access the site over an insecure connection, they will be redirected back to the same URL using SSL. If you are off loading SSL to a proxy, then you need to make sure that the proxy is supplying a X-Forward-Proto header, and that the proxy's IP address is set in Vireo's application.conf - XForwardSupport = 127.0.0.1

• auth.pass.enabled

• auth.pass.visible

  True / false configuration to enable and make visible the local password-based authentication.

• auth.pass.name

• auth.pass.description

  The user visible name and description of this authentication option. The description is only shown when the user is selecting between multiple authentication modules.

• auth.shib.enabled

• auth.shib.visibile

  True / false configuration to enable and make visible the Shibboleth-based authentication.

• auth.shib.name

• auth.shib.description

  The user visible name and description of this authentication option. Many campuses have branded their campus single sign on portal; configure these parameters to be something that your users will recognize.

• auth.shib.login.forceSSL = false

• auth.shib.login.url = /Shibboleth.sso/Login?target=%1s

• auth.shib.logout.url = /Shibbolesh.sso/Logout?return=%1s

  Configure the Shibboleth login and logout initiators. These are the url to which the user will be redirected in order to either initiate an authenticated session or close a session. The variable %1s will be replaced with a url where the user should be returned after completing the operation. Consult your Shibboleth configuration; however, these settings should be sufficient for most people. If the forceSSL parameter is true, then when the authentication request is initiated, the user will be redirected to use HTTPS. This only forces the login attempt to be over SSL; however the user could switch back to non-ssl for their session after authenticating if they change the URL in the browser. If the forceSSL parameter is false, the user will continue to use whichever protocol they are currently using; HTTP or HTTPS.

• auth.shib.primaryIdentifier = netid

  When authenticating a user via Shibboleth, one attribute must be used to uniquely identify the user in Vireo's account database. You can either use "NetID" or "email". It is always better to based the identifier on a NetID rather than email addresses because students often change their email addresses. However, the email option is available if needed.

• auth.shib.attribute.netid = SHIB_netid

• auth.shib.attribute.email = SHIB_email

• auth.shib.attribute.firstName = SHIB_givenName

• auth.shib.attribute.lastName = SHIB_sn

  The primary account attributes. Shibboleth will pass a user's attributes to Vireo as HTTP-based headers. The mapping above configures how these attributes are mapped into Vireo's data model. At a minimum you must map email, firstName, and lastName, and netid (if you are using it as the primary identifier).

• auth.shib.attribute.*

  The additional Shibboleth attributes. They are instutitionalIdentifier, middleName, displayName, birthYear, affiliations, currentPhoneNumber, currentPostalAddress, currentEmailAddress, permanentPhoneNumber, permanentPostalAddress, permanentEmailAddress, currentDegree, currentDepartment, currentCollege, currentMajor, currentGraduationYear, currentGraduationMonth.

Authorization

• advisor.affiliation.restrict = faculty

  This option requires that your authentication source (probably LDAP or Shibboleth) receive an attribute similar to eduPersonAffilation which describes how the person is affiliated with the institution. When this parameter is supplied then you can limit advisors to only those who have a particular affiliation(s). Supply all the acceptable affiliations below separated by a semicolon. If the list is empty or commented out, then all affiliations will be allowed to act as an advisor in Vireo and approve applications.

• submit.field.lock = personal

  Determine what fields should be locked during the submission process. If the authentication method is able to provide information about a person and that grouping of information listed below is locked, then the student will not be able to edit that information during submission. If the authentication mechanism is not able to provide the information, or it is invalid, then the student will always be able to edit the field no matter what the lock setting says. Available groups:

  • personal: first, middle, and last names along with birth year.
  • affiliation: department, degree, major.
  • contact: permanent and current phone, address, and email.

Secret Key

• application.secret

  This is basically the application's private key, so keep this safe! This is used to cryptographically sign the authentication cookies. Theoretically if someone were to gain access to this key, they could craft a cookie which would allow them to log in as anyone. Each deployment must use a completely random secret. Fortunately, you can run play secret to easily generate a new key. Also note that because this is used to sign the authentication cookie, changing this value and restarting the server has the effect of logging out all users.

• application.session.cookie=PLAY

• application.session.maxAge=1h

• application.session.secure=false

  All session information is stored in cookies persisted on the client side browser. Use these settings to change the name of the cookie, and the length of time the session cookie will persist.

Log Level

• application.log = INFO

  Specify the logging level for Vireo. The possible levels are:

  • FATAL: An unrecoverable error preventing the system from operating.
  • ERROR: Exceptions or unexpected errors. The current operation failed, but the application as a whole should be able to recover.
  • WARN: Potential problems such as deprecated APIs. The current operation completed successful.
  • INFO: Log basic usage information. This is the recommended level for production deployments.
  • DEBUG: Log basic information. This is recommended for developers working on the system.
  • TRACE: This will log a torrent of information from both the Play subsystems and Vireo. This is only useful for directed debugging.

• application.log.path = log4j.properties

  Ignore Play's logging configuration and use a log4j properties file to fully customize logging.

• application.log.system.out = off

  Configure whether the system should log the standard out.

Framework

• vireo.version = 2.0.1

  The version number of this Vireo instance. It is reported at several places in the UI and publicly visible.

• application.name = vireo2

  The name of the application. You probably don't ever need to change this.

• application.mode = prod

  Whether the application is in production or development mode. This affects several things such as whether the application will be pre-compiled and how friendly the error messages will be. If you need to change this, you should probably scope the change to a particular configuration framework.

• play.spring.namespace-aware = true

  Determine how namespaces are used in the Spring configuration. You probably don't ever need to change this.

• date.format=MM/dd/yyyy

  This is the default date format. You probably don't need to change this. We don't officially support non-American style dates yet. I expect we will in the future, but this has not yet been tested.