Installation overview

Transcription

1 hroot - Hamburg registration and organization online tool Universität Hamburg School of Business, Economics and Social Sciences WiSo- Research Laboratory Von- Melle- Park Hamburg Germany Installation overview hroot Installation hroot was developed using the programming language Ruby and the web framework Ruby on Rails. Installation procedure is more complex than regular desktop software, this document provides a step by step guide for the installation. Requirements Ruby on Rails and therefore hroot runs best in a Unix/Linux server environment, this is the case we will describe in this manual. Though it is possible to run Rails on a Windows environment, we have no experience in running hroot on a Windows server we will update this manual once we have gathered experience on Windows, but for now we recommend using a Unix/Linux environment. For a production environment, you typically need an Apache or Nginx web server, these servers operate best with rails projects. The Rails application itself will run a Ruby on Rails application server, typically Unicorn or Mongrel, but since in most cases you will want to embed hroot into a larger setting having other web sites and information resources too, it is best to run hroot using Unicorn or Mongrel and having a web server like Apache or Nginx to act as a proxy. You will also need a database server, we recommend installing the latest version of the MySQL server ( Installing Ruby When running Ruby on a server, one usually has the problem of running several different versions of the Ruby language simultaneously, as many operating systems have a version of the ruby language preinstalled. We recommend using RVM ( which enables you to install several ruby versions simultaneously, defining via a configuration file which version of ruby will be used. We recommend using RVM and following the instructions on For hroot, we recommend running ruby version or higher, which can be installed manually or using the RVM. If you choose to install ruby manually without the RVM, you can find detailed instructions for the manual ruby installation process on lang.org.

2 After installing ruby, you should be able to check the version using a shell via the command $ ruby --version Preparing the project directory and installing Bundler Most ruby packages are installed using the ruby package manger RubyGems (a gem is a ruby software package). RVM also supports the management of gemsets, which means that different softwareprojects requiring different versions of certain gems can be used on one machine, using the gemsets as a separating mechanism. We advise creating a fresh gemset for hroot. This is done via the command $ rvm gemset create hroot which will create a gemset with the name 'hroot' Create a directory for your hroot installation (for example projects/hroot in your home directory) and create a rvm configuration file named '.rmvrc'. Place the following line in the file: rvm use ruby-1.9.3@hroot This will instruct the rvm to use the Ruby version and the gemset 'hroot' in your project directory. For more information about gemsets and rvm configuration files please visit the rvm website. After creating the project directory and setting up Ruby and a gemset, you are ready to install bundler, which will help you install all necessary gems for the hroot project. Simply install it using RubyGems: $ gem install bundler This will install the latest version of bundler in your hroot gemset. Unpacking the source files and gem installation The next step is to unpack all the files from the hroot zip file to your project directory. In the main folder you can see a file named 'Gemfile'. This file contains information about the gem packages required for hroot. You can install all the gem packages, run the following command in your project home directory: $ bundle install After this step, all necessary gems including rails should have been installed. Initializing the database and testing the server Open the file config/database.yml to complete the database configuration. Rails projects typically have multiple configurations development and test databases

3 are used during implementation, the production database contains the real live data. Depending on your needs, provide access information for the databases by completing the information in the database.yml configuration file. After entering you database connection data, you can run the command $ rake db:setup This command will create the databases (if not already created), setup the database tables create an admin user. After the successful setup of the database, you can start the server for testing purposes. Run the command $ rails server in the root directory of your project. The server should now start, and you can access the server with a browser on your local machine (point your browser to During the database setup, an initial admin user is created: You can login with the address admin@domain.net and the password admin_ We recommend you change this password after your first login. Configuring the server There are a number of settings you can change, the possible settings are listed grouped by the file which contains the setting: config/application.rb config/database.yml config/environments/development.rb config/environments/production.rb config/initializers/devise.rb Configuration of time zone, default locale (set to :de for german, set it to :en for english) Database access as described above Detailed setup for development mode (including mail delivery, caching and default mail adresses) Detailed setup for production mode (including mail delivery, caching and default mail adresses) hroot uses the devise gem for authentication and the login process. You can change key parameters here.

4 You should have a look at all these files, especially to configure the functionality. You can find detailled instructions for rails configuration at Cron jobs hroot needs a number of cron jobs to perform its function. The cron jobs perform various operations, the most important is the mailing of experiment invitations and the general message queue. You can find the typical configuration of the cronjobs in the file config/schedule.rb, and you can generate the cron commands using the command $ whenever in your project root folder. The output can be added to your servers crontab. Importing from Orsee We have implemented a small script to import users from a standard Orsee database. To setup this importer script, open the file lib/tasks/import.rake. In the top of the file (line 8), you can enter the access information for the Orsee database. After entering the configuration information, you can run the import script with the following command: $ rake import:all or the following, if you want to import to your production database: $ RAILS_ENV=production rake import:all The script will import all subjects from the Orsee database. However we have found, that in many cases the database columns in Orsee were changed (or used in a different way), so importing data can require a deeper understanding of the database schema and ruby programming. If you run into trouble, don't hesitate to contact us, we will try to help you migrating you data to hroot. The import script will just import users, and it will require the addresses to be unique, so if an address is used twice, the second entry will be discarded. Due to the different role model of Orsee and hroot, administrative users (administrators, experimenters) are not imported.

5 Options for hosting a production environment So far we have covered the basic setup of a simple server just for demo purposes. If you want to run hroot on a web server in production mode, you have the following options: a) use Apache or Nginx in combination with phusion passenger (setup instructions at Phusion passenger is an application server which allows running rails projects together with an apache or nginx server. b) use a Unicorn server (detailed setup instructions at and use a web server as a proxy. c) find another alternative as described on Setup of a rails project in production mode can be difficult, ask for support of your local IT department, read the documentation of the two options or contact us, we can also support you with the setup.