Basic configuration

Most of the configuration values are located in the configuration files in the folder config/environments/<environment_name>.rb. We will first have a look at the configuration values in config/environments/development.rb for the development environment and then examine the differences in production.rb.

Each configuration file has the following structure:

Hroot::Application.configure do

  # configure values using config variable here
  config.some_configurable_variable = "some string value"
  config.some_other_configurable_variable = 12 # int values

end

# Some configurations are not part of the 'Hroot::Application.configure' block, they might go here

... more configuration settings...

Email server configuration

A lot of the configuration values deal with settings around sending emails. One important configuration item is to specify the mail server. Example one shows the configuration for a local sendmail server on port 25 (typical linux mail server):

config.action_mailer.delivery_method = :sendmail
config.action_mailer.smtp_settings = {
  :address              => "localhost",
 :port                 => "25"
}

You can also use any other mail service for sending mails, just be aware that this can be very slow and should only used for testing purposes. For example, you can use a gmail account for sending mails with the following configuration lines:

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  :address              => "smtp.gmail.com",
  :port                 => "587",
  :domain               => "googlemail.com",
  :user_name            => "<your_gmail_account>@googlemail.com",
  :password             => "<your_password>",
  :authentication       => "plain",
  :enable_starttls_auto => true
}

To actually send out emails, you have to enable delivery:

config.action_mailer.perform_deliveries = true

Since we want to be careful about sending emails to real users, the system is configured to only send emails to real users in production mode. You can however redirect all emails in development mode to an address of you choice to debug and test the system. To accomplish this, set an intercepter email:

config.interceptor_email = "<Your email>"

So the system only sends out emails to real users if you run in production mode, and the intercepter email is NOT configured.

You should set a default sender address for system mails:

config.hroot_sender_email = '<Some email which acts as default sender address>'

During the mailing of invitation emails, the system sends out some log information. You can configure the recipient of this log information with:

config.hroot_log_email = '<your email address>'

On some pages, an email address is printed to give the user information about where to get help. You can configure this address with

config.contact_email = '<Your contact email>'

If you generate links in your emails, the system needs to know about its url for generation of these email links. Let's say your hroot installation runs on https://www.yoursite.com/hroot, then the configuration of the email links would be

Rails.application.routes.default_url_options[:host] =  'www.yoursite.com/hroot'
Rails.application.routes.default_url_options[:protocol] =  'https'

Restricting email addresses

If you want to restrict the email addresses, which users can sign up with, you can configure a regular expression to describe valid email addresses. Example 1 - restrict to a single domain:

config.email_restriction = {
  :regex => /.*@somedomain\.org$/
}

Example 2 - Restrict to several different domains:

config.email_restriction = {
  :regex => /(.*@somedomain\.org$)|(.*@some-other-domain\.com$)|(.*@one-more-domain\.net$)/
}

You can author and test regular expressions with http://www.rubular.com. You can also find a quick reference for regular expressions in ruby on the same page.

Restrict/allow users to change optional data

When users log in to their account, they can browse all the data they have provided. Some of this data might be optional (like date of birth). Some users choose not to give you all optional information. Users can provide this data later on on their account page.

However, you can configure if this data can always be changed by users:

config.users_can_edit_optional_data = true

If you want to restrict this, set it to false

config.users_can_edit_optional_data = false

Now users can provide optional data, but once they have given you the information, they need to contact you or your staff to change the data again.

Upload directory

A fairly new and for now experimental feature is the file upload, where you can upload documents to each experiment. The path to the location of the file storage can be configured, by default it's

config.upload_dir = Rails.root.join('uploads')

You can set it to any path, just make sure, that the web server user has full permissions to read, write and create folders:

config.upload_dir = '/some/custom/path/for/files'

Exception mailing

You can configure the server to send out emails in case some error occurs. This is especially useful, when you start developing changes for your own, and you want to monitor the site more closely. To enable exception messaging, first enable it with

config.catch_exceptions = true

At the end of the configuration file, you can find a template where you can set the recipient of the error reports, as well as a prefix for the exception mails (useful for filtering exception mails in your inbox). Insert your email address, a sender address and a prefix to following code block to enable exception notification via email:

Hroot::Application.config.middleware.use ExceptionNotification::Rack,
  :email => {
    :email_prefix => "[<your email prefix>] ",
    :sender_address => %{"<some@email.adress>"},
    :exception_recipients => %w{<some@email.adress>}
  }

Server settings (optional read)

The following settings are part of all Rails projects and are not specific to hroot. In most cases you can just leave all the settings with their default setting. We provide a short overview of the meaning:

Caching classes

With this option you can define if the classes should be reloaded on each request. During development, this is useful, so you can immediately see changes to the code. This is of course slow, so it should be disabled in production.

# in development mode, don't cache classes
config.cache_classes = false

# in production mode, cache classes
config.cache_classes = true

Log settings

A number of variables define the logging behaviour and behaviour in case an error occurs. In development mode, the most common settings are:

# Log error messages when you accidentally call methods on nil.
config.whiny_nils = true

# Show full error reports and disable caching
config.consider_all_requests_local       = true
config.action_controller.perform_caching = false

# Don't care if the mailer can't send
config.action_mailer.raise_delivery_errors = false

# Print deprecation notices to the Rails logger
config.active_support.deprecation = :log

# Only use best-standards-support built into browsers
config.action_dispatch.best_standards_support = :builtin

# configures javascript assets to be debuggable (so you can inspect Javascript in the browser)
config.assets.debug = true

# configures the log level (what should be printed to the logfiles)
config.log_level = :info