Fetching contributors…
Cannot retrieve contributors at this time
248 lines (181 sloc) 9.16 KB
__ __ _ _ _
| \/ | __ _ _ __| | _| | | |___
| |\/| |/ _` | '__| |/ / | | / __|
| | | | (_| | | | <| |_| \__ \
|_| |_|\__,_|_| |_|\_\\___/|___/
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)
* ImageMagick (known to work with >=6.5.7, 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 IMAGEMAGICK (OPTIONAL)
If you plan on using MarkUs' PDF conversion feature so that you can annotate
them using a browser, you need ImageMagick installed.
To make sure you have ImageMagick installed, run:
identify --version
If you don't http://www.imagemagick.org/script/install-source.php#unix
has detailed instructions on installing ImageMagick.
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