INSTALL

 __  __            _    _   _
|  \/  | __ _ _ __| | _| | | |___
| |\/| |/ _` | '__| |/ / | | / __|
| |  | | (_| | |  |   <| |_| \__ \
|_|  |_|\__,_|_|  |_|\_\\___/|___/


Thanks for using MarkUs!

NOTE: These are production install instructions.  If you are a MarkUs 
  developer, please follow setup instructions here:
  http://github.com/MarkUsProject/Markus/wiki

ALSO NOTE: You may find the install instructions on our Wiki page easier to
           read than this text file.  The install instructions on our Wiki
           can be found here:
           https://github.com/MarkUsProject/Markus/wiki/InstallProdStable

1. WHAT YOU NEED TO KNOW

MarkUs is a Web application using the Ruby on Rails framework. By design, MarkUs
supports one course per installation. I.e. two different courses require two
installed instances of MarkUs. Please keep that in mind for the following
installation process.

2. DOWNLOAD MARKUS

You can download MarkUs from our website
see http://www.markusproject.org/download/

3. INSTALLATION INSTRUCTIONS

3.1 REQUIRED SOFTWARE

  As mentioned previously, MarkUs is a Ruby on Rails application. General
  requirements are as follows (Note: MarkUs also works using Phusion Passenger):

    * Ruby (version 1.8.7) (version 1.9.x are not supported yet)
    * Ruby development package (required for compiling Ruby PostgreSQL drivers)
    * net/https Ruby library (libopenssl-ruby Debian package)
    * RDoc (required for Gem)
    * Debian 'build-essential' equivalent packages (gcc, make, libc6-dev, etc.)
      These packages are required for building PostgreSQL/MySQL gem packages
    * Subversion including Ruby bindings
    * Gem (version 1.3.7 and higher)
    * The following Ruby gems:
        - bundler (1.0.3 and higher)
    * Apache httpd (version 2.2 and higher) including the following modules:
        - mod_proxy
        - mod_rewrite
        - mod_dav_svn (required if you want to allow SVN repository access)
        - mod_authz_svn (required if you want to allow SVN repository access)
    * Ghostscript (known to work with >=9.05, older versions should be ok too)
      Only required if you plan to be able to view and annotate pdfs within
      the browser (PDF_SUPPORT setting in config files)
    * Ant, if you plan to use the MarkUs built in testing framework (still in
      alpha)

  DATABASE THINGS

  We know that MarkUs works with either PostgreSQL or MySQL databases.

    MarkUs/PostgreSQL:
    If you plan to use MarkUs with a PostgreSQL database, you need the following
    software

      * PostgreSQL
      * Development package(s) for PostgreSQL
      * Ruby gems (Bundler will handle those):
          - pg (version 0.10.1 and higher)

    MarkUs/MySQL:
    If you plan to use MarkUs with a MySQL database, you need the following
    software

      * MySQL (Bundler will handle those):
      * Development package(s) for MySQL
      * Ruby gems (Bundler will handle those):
          - mysql (version 2.8.1 and higher)

  If you are using a Debian based Linux distribution (such as Ubuntu) you could
  install the above required software by using commands similar to the
  following:

  PostgreSQL option:

    sudo aptitude install ruby ruby-dev rdoc libopenssl-ruby postgresql \
    libpq-dev subversion libsvn-ruby apache2 libapache2-svn

  MySQL option:

    sudo aptitude install ruby ruby-dev rdoc mysql-server libmysqlclient15-dev \
    subversion libsvn-ruby libopenssl-ruby apache2 libapache2-svn

  INSTALLING RUBYGEMS

  Installing gem (version 1.3.7 and higher) on Debian based systems:

      Use rubygems package on your system (for Debian/Ubuntu) :
        sudo aptitude install rubygems

      or

      Download rubygems from rubyforge.org (see
      http://rubyforge.org/projects/rubygems/); We show the steps for version
      1.3.7:
	wget http://rubyforge.org/frs/download.php/70696/rubygems-1.3.7.tgz
        tar -xzf rubygems-1.3.7.tgz
        cd rubygems-1.3.7
        sudo ruby setup.rb
        sudo mv /usr/bin/gem /usr/bin/gem.old # if you have an older gem version
                                                installed
        sudo ln -s /usr/bin/gem1.8 /usr/bin/gem
        gem -v                                # for confirmation

      Once you've installed rubygems, you'll want to tell Ruby to load rubygems
      automatically.  This is done by setting the RUBYOPT environment variable
      to rubygems.  Example (assuming BASH shell):

      export RUBYOPT=rubygems

      You'll probably want to put this in your .bashrc (or equivalent) as well.

      See http://docs.rubygems.org/read/chapter/3 for further details.


3.2 GHOSTSCRIPT (OPTIONAL)

  If you plan on using MarkUs' PDF conversion feature so that you can annotate
  them using a browser, you need Ghostscript installed.

  To make sure you have Ghostscript installed, run:

    ghostscript --version
	
  If you don't http://ghostscript.com/doc/9.05/Install.htm#Install_Unix
  has detailed instructions on installing Ghostscript. 


3.3 INSTALLING MARKUS

  Once you have the required software installed, it should be pretty straight-
  forward to install MarkUs. We assume you have a database user with appropriate
  permissions set up.

  * Get a copy of the MarkUs tarball:
      wget http://www.markusproject.org/download/markus-latest-stable.tar.gz
  * Extract the tarball to the desired location
      tar -xzvf markus-latest-stable.tar.gz
  * You should have a directory called markus-X.Y.Z now. Change to MarkUs'
    application root. For example:
      cd markus-0.9.0
  * Install Rails and required Ruby gems: see section 3.4 "GETTING RAILS
    AND RUBYGEMS".
  * Set environment variable ::Rails.env (assumes BASH)
      export ::Rails.env="production"
  * Configure database connection settings to match your settings
      PostgreSQL option:
        cp config/database.yml.postgresql config/database.yml
      MySQL option:
        cp config/database.yml.mysql config/database.yml
  * Configure MarkUs to match your requirements. Please have a look at
    config/environments/production.rb. This file is well documented and
    your instance specific configuration has to be done in there. Further
    information can be found here:

    https://github.com/MarkUsProject/Markus/wiki/InstallProdStable

    If you have questions, please feel free to get in touch with us:
    markus-users@cs.toronto.edu
  * Create the database for MarkUs
      bundle exec rake db:create
  * Load the database schema for MarkUs
      bundle exec rake db:schema:load
  * Create an instructor (for initial login)
      bundle exec rake markus:instructor first_name="test" last_name="test" \
      user_name="markus"
  * Configure Apache httpd (optional, see example config below)
  * Configure Mongrel or Passenger servers (config/mongrel_cluster.yml)
    see http://github.com/MarkUsProject/Markus/wiki/ApacheMongrel
    or http://github.com/MarkUsProject/Markus/wiki/ApachePassenger
  * Once MarkUs boots up fine (script/server runs without errors), you can start
    the mongrel cluster
      mongrel_rails cluster::start
    see log files (log/mongrel.800x.log) for success/failure messages
  * That's it!

If you run into any problems please send e-mail to markus-users@cs.toronto.edu.
We are happy to help and would also like to hear your feedback! Please include
the version number of MarkUs you are using. You can find out about the version
you are currently using by issuing the following command:
  bundle exec rake -s markus:version


3.4 GETTING RAILS AND REQUIRED GEMS

  Bundler and required ruby gems (including rails) can be installed like
  so:

    sudo gem install bundler

  Make sure "bundle" is in $PATH (assuming BASH). We need to find the
  installation location of bundler for this. The following commands may
  be helpful:

    gem env | grep -A3 'GEM PATHS'     # shows path to gems

  An example for setting PATH is shown below:

    export PATH=$PATH:/usr/lib/ruby/gems/1.8/gems/bundler-1.0.3/bin

  Consider adding the above export to your ~/.bashrc.

  To get all required gems for MarkUs in one shot (this should take care of
  versions too) you'll want to use the bundle install command. However, you'll
  probably want to tell bundler to skip over development and test environment
  gems, as well as gems for databases that you're not using.

  For example, if you were setting up a production version of MarkUs using
  a PostgreSQL database backend, you'd want to execute:

  bundle install --without development test sqlite mysql

  Similarly, if you were setting up a production version of MarkUs using
  a MySQL database backend, you'd want to execute:

  bundle install --without development test sqlite postgresql

  Note that these commands may be executed as a non-root user.


4. FURTHER INSTRUCTIONS, FAQ, LINKS

  * http://github.com/MarkUsProject/Markus/wiki/Home
  * http://github.com/MarkUsProject/Markus/wiki/InstallProdStable
  * http://github.com/MarkUsProject/Markus/wiki/MultipleHosting
  * http://www.markusproject.org/dev/markus_httpd_vhost.conf
  * See available rake tasks for MarkUs: "bundle exec rake -T markus" or 
    more generically
    "bundle exec rake -T"

5. BUGS

If you think you have found a bug, you can file a bug report or contact
developers at markus-dev@cs.toronto.edu. Feel free to provide a patch ;-)

  http://github.com/MarkUsProject/Markus/issues