Configuration - YaleSTC/reservations GitHub Wiki

Reservations Configuration

In order to configure a deployment of Reservations, there are a number of environment variables that need to be set. We're using dotenv and dotenv-deployment to simulate the presence of environment variables for Rails in situations where they aren't actually defined in the system, but these do not need to be used. The following document details the environment variables that need to be set and how they are used.

Contents:

Authentication

The first of these environment variables must be set in all Rails environments (e.g. development, test, and production) in order to use CAS authentication, otherwise e-mail/password authentication will be used (see here for more details).

CAS_AUTH

The presence of this environment variable determines whether or not to use CAS authentication (if it is present / defined to any value, CAS authentication is used). The decision of whether or not to use it should be made even before the initial setup for the application as it will modify the creation of the first user / superuser. The switching of authentication methods from CAS to e-mail/password and vice versa is supported by Reservations, with some caveats (for more information see here). If CAS authentication is used, the following environment variable must be defined.

CAS_BASE_URL (production only)

This environment variable defines the base url of the CAS authentication server (e.g. https://secure.its.yale.edu/cas/). It is only necessary if using CAS authentication, and only in the production Rails environment. It is defined in config/secrets.yml for the development and test Rails environments.

DEVISE_SECRET_KEY (production only)

This environment variable stores the secret key used by Devise to generate random tokens. It should be set to a random token which can be generated by rake secret (produces a pseudo-random 128-character hexidecimal string). It is defined in config/secrets.yml for the development and test Rails environments. This should be unique for each instance deployed to a given server/domain!

DEVISE_PEPPER (production only)

This environment variable stores the "pepper" used by devise to help generate encrypted passwords. It should be set to a random token Like DEVISE_SECRET_KEY. It is only necessary if using e-mail / password authentication. It is defined in config/secrets.yml for the development and test Rails environments. This should be unique for each instance deployed to a given server/domain!

Rails

These environment variables only need to be defined in the production Rails environment. If necessary, their default values are defined in config/secrets.yml.

RAILS_RELATIVE_URL_ROOT

This environment variable is used to configure Reservations for subdirectory deployment, e.g example.com/reservations. It should be set to the relative location of the application root (e.g. /reservations).

SECRET_KEY_BASE

This environment variable stores the secret key used by Rails to sign cookies / sessions. It should be set to a random token like DEVISE_SECRET_KEY and DEVISE_PEPPER. It is defined in config/secrets.yml for the development and test Rails environments. This should be unique for each instance deployed to a given server/domain!

Database

These environment variables only need to be defined in the production Rails environment. The database configuration for the development and test Rails environments should be done manually in config/database.yml.

RES_DB_NAME

This environment variable stores the name of the database that will be used in production (see config/database.yml.example.production). A simple example might be reservations_production.

RES_DB_USERNAME

This environment variable stores the MySQL or PostgreSQL username used to access the database.

RES_DB_PASSWORD

This environment variable stores the MySQL or PostgreSQL password used to acccess the database.

RES_DB_HOST

This environment variable stores the hostname or location of the MySQL or PostgreSQL database server. For applications where the application server also serves as the database server this might be localhost.

E-Mail

These environment variables only need to be defined in the production Rails environment. If necessary, their default values are defined in config/secrets.yml.

DISABLE_EMAILS

This environment variable can be used to disable ALL e-mails sent by Reservations (useful for deployments using the Rails "production" environment on test or staging servers). Like CAS_AUTH, set it to any value to disable all e-mails.

RES_SMTP_ADDRESS

This environment variable stores the hostname or location of the SMTP server used for sending e-mails, e.g. smtp.example.com.

RES_SMTP_PORT

This environment variable stores the port used to talk to the SMTP server, e.g. 587.

RES_SMTP_DOMAIN

This environment variable stores the domain used to send e-mails from, e.g. example.com.

RES_SMTP_AUTH

This environment variable determines whether or not the SMTP server accepts authentication. Like CAS_AUTH, set it to anything to turn on SMTP authentication. If it is set, the following two environment variables must be defined.

RES_SMTP_USERNAME

This environment variable stores the username for SMTP authentication. It is only required if RES_SMTP_AUTH is set.

RES_SMTP_PASSWORD

This environment variable stores the password for SMTP authentication. It is only required if RES_SMTP_AUTH is set.

RAILS_HOST_NAME

This environment variable stores the hostname of the Reservations instance, e.g. example.com. It is used to ensure that links in e-mails all work correctly.

LDAP

The first of these environment variables must be set in all Rails environments (e.g. development, test, and production) in order to use LDAP user lookup. The remaining environment variables only need to be defined in the production Rails environment. If necessary, their default values are defined in config/secrets.yml.example.

USE_LDAP

This environment variable determines whether or not to enable LDAP user lookup. Like CAS_AUTH, set it to anything to turn on LDAP lookup. If it is set, the following eight environment variables must be defined.

RES_LDAP_HOST

This environment variable stores the hostname or location of the LDAP server for user lookups, e.g. directory.example.com.

RES_LDAP_PORT

This environment variable stores the port used for LDAP user lookups, e.g. 389.

RES_LDAP_BASE

This environment variable stores the base used for LDAP lookups, e.g. o=example.com,ou=People.

RES_LDAP_LOGIN

This environment variable stores the LDAP field that corresponds to the username for CAS authentication, e.g. username.

RES_LDAP_EMAIL

This environment variable stores the LDAP field that corresponds to the e-mail for e-mail/password authentication and generalized lookup, e.g. mail.

RES_LDAP_FIRST_NAME

This environment variable stores the LDAP field that corresponds to the first name of a user, e.g. firstname.

RES_LDAP_LAST_NAME

This environment variable stores the LDAP field that corresponds to the last name of a user, e.g. lastname.

RES_LDAP_NICKNAME

This environment variable stores the LDAP field that corresponds to the nickname of a user, e.g. nickname.

RES_LDAP_AFFILIATION

This environment variable stores a comma-separated list of LDAP fields that are concatenated together to generate the affiliation of a user, e.g. college,class

PartyFoul

This environment variable only needs to be set in the production Rails environment as PartyFoul will not be used in the development environment.

PARTY_FOUL_TOKEN

This environment variable stores the GitHub OAuth token used by PartyFoul to create issues on a fork of Reservations when exceptions are caught in production.

Static Assets

This environment variable only needs to be set in the production Rails environment as it is only used in config/environments/production.rb.

SERVE_STATIC

Set this environment variable to any value to enable static asset serving via Rails (like CAS_AUTH). This is primarily used in Heroku deployment; it should not be set in other deployment environments unless it is definitely needed.