Installation, Setup, and Customization

Obtaining the Code

The source code for OpenBrewComp is easily obtained by cloning the github repository: 

git clone git://github.com/davec/openbrewcomp.git

Alternatively, you can download an archive of the source code by clicking the download button at the top of the project’s github page and unarchiving it to a local directory.

Branching

If you are using git, it is highly recommended that you create a branch for your own modifications. By keeping your modifications on a separate branch, you will be able to update to a newer release of OpenBrewComp by fetching the master branch from github and using git rebase or git merge to apply the master branch modifications to your branch.

Similarly, when submitting patches, you should create a separate branch, based on the master branch, in which you create your patches that you will be submitting.

Please visit the git documentation page for more detailed information on managing projects with git.

Initial Configuration

Once you have a copy of the source code installed (and preferably checked into your own source code repository), follow these steps to configure the system:

  1. Copy config/database.yml.example to config/database.yml and edit it for your environment. Sample configurations for both PostgreSQL and MySQL are provided.
  2. Run rake setup to generate a set of required configuration files. At the conclusion of the setup process, instructions pertaining to the generated files will be printed to the screen. Read, and follow, them.
  3. Run rake gems:install to install the required gems.
  4. Edit db/fixtures/contacts.yml and set the contact information for your competition coordinator and webmaster.
  5. [Optional] Edit db/fixtures/clubs.yml to set an initial list of clubs that will be shown in a selection box for an entrant to choose from. This is not strictly necessary since entrants will be able to add their own club’s name to the list if it does not already exist in the database, but an initial list of clubs that only has your own club name doesn’t look so good.
  6. Create your development, test, and production databases with rake db:create:all
  7. Initialize your development database with rake db:bootstrap

Testing

Now that you have the system configured, make sure it is functioning properly by running rake test to perfom some basic functionality tests. If anything fails, you need to investigate the failure(s) before proceeding.

Note that the functional tests generate a large number of deprecation warnings. These warnings are expected and are not a problem.

Customization

Although some customization was previously performed during the initial configuration, additional customization will be required to complete the setup. The files that need to be modified are as follows:

app/models/style.rb

Modify the number_of_bottles_required method as appropriate for your competition. The default is 3 bottles for “point qualifying” styles, i.e., those that are judged in a best-of-show flight, and 2 bottles for all other styles.

app/models/award.rb

The MAX_ENTRIES variable defines the maximum number of entries per award category, and defaults to 2. Set this value as appropriate for your competition. If you do not impose a limit, set it to nil.

Note, however, that this is not a hard limit and does not prevent someone from actually entering more than the allowed number of entries — an annoying warning message will be displayed with each entry that is registered in excess of the maximum value — but it is the responsibility of the competition organizer to enforce the limit, and an administrative report is available to identify such entries.

If your competition imposes some other type of entry limits, for example, on a per-style basis, other code modifications will be required.

config/initializers/action_mailer.rb

Configure your email server settings. Failure to set these correctly will prevent any email from being sent.

config/initializers/exception_notifier.rb

Configure the recipients for email notification of any exceptions that are encountered in the production environment.

config/initializers/session_cleanup.rb

Configure database-stored session expiry time. The default is 2 hours. You will need to create a cron job to periodically purge the expired sessions from the database.

The following shell script, called periodically from a cron job, will purge the expired sessions: 

#!/bin/sh
# Usage: expire-rails-sessions application environment
if [ $# -eq 2 ] ; then
  cd /var/www/rails/$2/$1/current
  script/runner -e $2 SessionCleanup.purge_expired_sessions
else
  echo "Usage: $0 application environment"
fi

As an alternative to the database-stored sessions, you may prefer to use the default cookie-based session storage instead. If so, modify config/environment.rb and comment out the setting for config.action_controller.session_store.

app/models/judge_invite.rb

The judge invite template can be modified to suit your taste. This is the message template that is shown on the Judge Invites page, and unless you want to permanently change the default message, you do not need to make any changes here and can make one-time modifications when you send the invites.

International Issues

By default, the system will accept entries from brewers in the United States and Canada. Settings in the administrative interface control the display of countries and testing has shown no problems with including other countries that generally follow similar postal addressing formats, e.g., Australia, Brazil, and Mexico.

Inclusion of other countries in the registration form is a simple matter of setting an option in the countries table. However, support for countries that do not generally follow US/Canada addressing formats, e.g., most of Europe, will require some modifications to the entrant and judge registration forms to properly handle the different address formats.

Since this application was originally built for competitions in the United States, the addresses printed on the entrant cover sheets assume that they will be mailed from within the US and only append a country name for non-US recipients. If you are located outside the US, a simple change can be made to change the addressing behavior — edit app/models/country.rb and modify the include_country_in_address? method, following the comments found there.

Customizing the Presentation

Adjust the page layouts (in the app/views/layouts directory) and tweak the CSS (in the public/stylesheets directory) to customize the look for your competition.

Several pages are provided as stubs in the various app/views/* directories. You should modify these files as appropriate for your site, including, but not limited to, app/views/about/faq.html.erb, app/views/about/privacy.html.erb, app/views/entries/rules.html.erb, and app/views/entries/shipping.html.erb.

Customizing the Results

The layouts for reporting the results of the competition are located in the app/views/admin/results directory. The files bjcp.html.erb, bjcp.xml.builder, mcab.html.erb, and _mcab.html.erb located there should not require any modification.

The cover sheets for returned score sheets are specified in entrant_covers.rtex which needs to be edited to specify the proper return address for your competition. Search for ReturnAddr and make the appropriate modifications to the address elements. You are, of course, free to modify the return address section in any way you want, as long as it is valid LaTeX code.