Skip to content

Latest commit

 

History

History
128 lines (76 loc) · 6.97 KB

INSTALL.md

File metadata and controls

128 lines (76 loc) · 6.97 KB
Raw

Calagator

Setup

You will need to:

  • Install git, a distributed version control system. Read the Github Git Guides to learn how to use git.
  • Install Ruby, a programming language. You can use MRI Ruby 1.8.7, or Phusion REE (Ruby Enterprise Edition). Your operating system may already have it installed or offer it as a pre-built package.
  • Install RubyGems 1.3.x or newer, a tool for managing software packages for Ruby.
  • Install SQLite3, a database engine. Your operating system may already have it installed or offer it as a pre-built package.
  • Install Bundler, a Ruby dependency management tool. You should run gem install bundler as root or an administrator after installing Ruby and RubyGems.
  • Checkout the source code. Run git clone git://github.com/calagator/calagator.git, which will create a calagator directory with the source code. Go into this directory and run the remaining commands from there.
  • Install Bundler-managed gems, the actual libraries that this application uses, like Ruby on Rails. You should run bundle, which may take a long time to complete.
  • Optionally specify the theme to use, see the Customizing section for details.
  • Optionally setup API keys for external services so that maps will be displayed, see the API Keys section for details.
  • Start the search service if needed, see the Search engine section for details.

Development

To run Calagator in development mode, which automatically reloads code as you change it:

  • Follow the Setup instructions above.
  • Initialize your database, run bundle exec rake db:migrate db:test:prepare
  • Start the Ruby on Rails web application by running rails server (UNIX) or ruby script/rails /server (Windows).
  • Open a web browser to http://localhost:3000/ to use the development server
  • Read the Rails Guides to learn how to develop a Ruby on Rails application.
  • When done, stop the Ruby on Rails server (e.g. rails server) by pressing CTRL-C.

Production

To run Calagator in production mode, which runs more quickly, but doesn't reload code:

  • Follow the Setup instructions above. Don't forget to do things like create the theme and secrets files.
  • Setup a firewall to protect ports used by your search engine, see the Search engine section for details.
  • Initialize your database, run bundle exec rake RAILS_ENV=production db:migrate
  • Run bundle exec rake clear to clear your cache after updating your application's code.
  • Setup a production web server using Phusion Passenger, Thin, Unicorn, Rainbows, etc. These will be able to serve more users more quickly than using the built-in server (e.g. rails server).

The Calagator.org site runs on Ubuntu Linux, Phusion REE (Ruby Enterprise Edition) and Phusion Passenger.

Customization

If you want to customize your Calagator, do NOT just start modifying files in app, public and themes/default. Please read the instructions in themes/README.txt for how to use the theming system.

Security and secrets.yml

This application runs with insecure settings by default to make it easy to get started. These default settings include publicly-known cryptography keys that can allow attackers to gain admin privileges to your application. You should create a config/secrets.yml file with your secret settings if you intend to run this application on a server that can be accessed by untrusted users, read the config/secrets.yml.sample file for details.

Spam Blacklist

A default set of blacklist words is provided in config/blacklist.txt. You can create your own by adding a config/blacklist-local.txt file with one regular expression per line (see config/blacklist.txt for examples).

API Keys

The application uses a number of API keys to communicate with external services.

  • Yahoo! Upcoming: To import events from Upcoming, the application can use a public key, but for production use, you should really get and use your own API key. See the config/secrets.yml.sample file's upcoming_api_key section for details.

  • Google Maps: To display Google maps, you must get an API key. For details, see the config/geocoder_api_keys.yml.example for details.

Search engine

You can specify the search engine to use in your config/secrets.yml file:

sql

Default search engine which uses SQL queries. Requires no additional setup, dependencies or service. Does not provide relevance-based sorting. Provides substring matches.

sunspot

Optional search engine that uses the Sunspot gem. Requires additional setup, dependencies and service. Provides relevance-based sorting. Does not provide substring matches.

To use, you will need to install Java 1.6.x, a programming language used to run the search service.

You will then need to initially populate your records by running commands like:

bundle exec rake RAILS_ENV=production sunspot:solr:start
bundle exec rake RAILS_ENV=production sunspot:reindex:calagator

You can start the Solr search service a command like:

bundle exec rake RAILS_ENV=production sunspot:solr:start

You can stop the Solr search service a command like:

bundle exec rake RAILS_ENV=production sunspot:solr:stop

You should setup a firewall to protect the ports that the Solr search service runs on. These ports are described in the config/sunspot.yml file.

acts_as_solr

Optional search engine that uses the acts_as_solr gem. Requires additional setup, dependencies and service. Provides relevance-based sorting. Provides substring matches. However, has severe performance problems that may slow down creating and editing records.

To use, you will need to install Java 1.6.x, a programming language used to run the search service.

You will then need to initially populate your records by running a command like:

bundle exec rake RAILS_ENV=production solr:rebuild_index

You can start the Solr search service a command like:

bundle exec rake RAILS_ENV=production solr:start

You can stop the Solr search service a command like:

bundle exec rake RAILS_ENV=production solr:stop

You should setup a firewall to protect the ports that the Solr search service runs on. These ports are described in the config/solr.yml file.

Feedback wanted

Is there something wrong, unclear or outdated in this documentation? Please get in touch so we can make it better. If you can contribute improved text, we'd really appreciate it.