Installation Manual

Introduction
The thBook System is a web-based application, running through most modern web browsers. Therefore, setup for the end user is trivial, and the deployment team on the back end must take most steps during installation.

The following components make up the back-end for the system:

This guide will cover installation of a development environment for Linux-based servers only.
 * An Apache web hosting server, with an active Internet connection
 * Ruby
 * RubyGems
 * Ruby On Rails
 * MySQL Server

Installing Ruby + Ruby On Rails
taken from [1], [5] and [6]

Installing Ruby
Ruby is a scripting programming language the Rails framework is written on. Ruby 1.9.3 is recommended for use with Rails. Rails 3.2 is the last one that supports Ruby 1.8. Ruby 1.8.6 and earlier are not supported, neither is version 1.9.1.


 * Download and extract the ruby source code at ftp://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.3-p0.tar.gz
 * follows the instructions given on the README file placed on the root directory to install ruby

Installing RubyGems
RubyGems. It's similar to apt-get, emerge, and other OS package managers. RubyGems is already available on some linux distributions, but if you don't have it : If you do have it already :
 * Download and extract the package manager at http://production.cf.rubygems.org/rubygems/rubygems-1.8.21.zip
 * run "ruby setup.rb" (you may need root privilieges)
 * gem update --system

Installing rails
With RubyGems loaded, you can install all of Rails dependencies through the command : gem install rails New versions of Rails can be installed the same way.

Getting the source code
Install your favourite Mercurial (hg) client and Clone the repository wherever you want : hg clone http://hg.assembla.com/thbook

Rails applications use by default a SQlite3 database. As we want to use a MySQL Database for our development, change the development section of the config/database.yml file to : development:  adapter: mysql2 encoding: utf8 database: blog_development pool: 5 username: root password: socket: /tmp/mysql.sock

Installing Apache
taken from [7].

As most Linux distributions come with Apache pre-installed, this installation guide will assumes you already have a working version of Apache2.

Install Phusion Passenger module
Phusion Passenger is an Apache module, which makes deploying Ruby and Ruby on Rails applications on Apache a breeze. It follows the usual Ruby on Rails conventions, such as "Don’t-Repeat-Yourself" and ease of setup, while at the same time providing enough flexibility.

To install passenger, type : gem install passenger passenger-install-apache2-module Then follow the instructions given from the shell prompt.

Apache Server Settings
The following apache Directory settings may be used as an example of a project where the system source code has been cloned into "/home/robson/projects/thbook" : ​ ServerName thbook.local # be sure to point to 'public'! DocumentRoot "/home/robson/projects/thbook/public" RailsEnv development  # relax Apache security settings AllowOverride all # <-- MultiViews must be turned off Options -MultiViews  

MySQL 5.x installation
taken from [8].

There are several options for how to install MySQL:

The rest of this chapter deals with the 4th option –the installation of MySQL from the source.
 * using YaST – the easiest and fastest way. However, the version of MySQL bundled with SuSE installation is usually NOT the best (i.e. the most recent) available,
 * RPM installation – supposedly also fast and simple, I’ve never tried though. The only drawback here is that MySQL is not installed into a single destination – it’s scattered across several directories. I like to keep things tidy, so I skipped this option,
 * installing binaries – downloading precompiled files from the mysql.com website, copying them into a directory of your choice, and doing some simple configuration. I tried this, but it didn’t work for me – for some reason the MySQL server wouldn’t start,
 * installing from source – I would recommend this. Yes, it takes some time and effort, but you will get the most recent MySQL installed in a single location on your system, and everything will be configured according to your needs.

Prerequisites
Make sure you have superuser (root) privileges and user “mysql” already exists in your system. If not, create one: groupadd mysql useradd -g mysql mysql <p style="margin-top: 0.5em; margin-bottom: 0px; border-style: initial; border-color: initial; outline-width: 0px; outline-style: initial; outline-color: initial; font-size: 14px; background-image: initial; background-attachment: initial; background-origin: initial; background-clip: initial; text-align: left; color: rgb(38, 50, 72); font-family: DINPro, Verdana, Arial, sans-serif; font-style: normal; line-height: 19px;">This will be the default user under which the MySQL server will be running.

Download the source
<p style="margin-top: 0.5em; margin-bottom: 0px; border-style: initial; border-color: initial; outline-width: 0px; outline-style: initial; outline-color: initial; font-size: 14px; background-image: initial; background-attachment: initial; background-origin: initial; background-clip: initial; text-align: left; color: rgb(38, 50, 72); font-family: DINPro, Verdana, Arial, sans-serif; font-style: normal; line-height: 19px;">First, download the MySQL source at http://dev.mysql.com/downloads/mysql/5.0.html#source. You need the <span style="border-style: initial; border-color: initial; outline-width: 0px; outline-style: initial; outline-color: initial; background-image: initial; background-attachment: initial; background-origin: initial; background-clip: initial; background-color: transparent; color: rgb(255, 0, 0); ">mysql-5.1.52-linux-i686-glibc23.tar.gz tarball file (or <span style="border-style: initial; border-color: initial; outline-width: 0px; outline-style: initial; outline-color: initial; background-image: initial; background-attachment: initial; background-origin: initial; background-clip: initial; background-color: transparent; color: rgb(255, 0, 0); ">mysql-5.1.52-linux-x86_64-glibc23.tar.gz for 64-bit systems).

Unpack, configure, compile
tar -xzf mysql-5.1.52-linux-i686-glibc23.tar.gz cd mysql-5.1.52-linux-i686-glibc23/ ./configure --prefix=/usr/local/mysql-5.1.52 --with-charset=utf8 --with-collation=utf8_general_ci make make install

<p style="margin-top: 0.5em; margin-bottom: 0px; border-style: initial; border-color: initial; outline-width: 0px; outline-style: initial; outline-color: initial; font-size: 14px; background-image: initial; background-attachment: initial; background-origin: initial; background-clip: initial; text-align: left; color: rgb(38, 50, 72); font-family: DINPro, Verdana, Arial, sans-serif; font-style: normal; line-height: 19px;">We used the –with-charset and –with-collation options to set the default character set and collation – otherwise it would have been the default Swedish collation.

<p style="margin-top: 0.5em; margin-bottom: 0px; border-style: initial; border-color: initial; outline-width: 0px; outline-style: initial; outline-color: initial; font-size: 14px; background-image: initial; background-attachment: initial; background-origin: initial; background-clip: initial; text-align: left; color: rgb(38, 50, 72); font-family: DINPro, Verdana, Arial, sans-serif; font-style: normal; line-height: 19px;">I recommend creating a symbolic link called “mysql” pointing to the MySQL installation directory, in order to make referring to it from elsewhere easier: ln -s /usr/local/mysql-5.1.52/ /usr/local/mysql <p style="margin-top: 0.5em; margin-bottom: 0px; border-style: initial; border-color: initial; outline-width: 0px; outline-style: initial; outline-color: initial; font-size: 14px; background-image: initial; background-attachment: initial; background-origin: initial; background-clip: initial; text-align: left; color: rgb(38, 50, 72); font-family: DINPro, Verdana, Arial, sans-serif; font-style: normal; line-height: 19px;">This way we can always refer to MySQL installation directory as <span class="dirPath" style="border-style: initial; border-color: initial; outline-width: 0px; outline-style: initial; outline-color: initial; background-image: initial; background-attachment: initial; background-origin: initial; background-clip: initial; background-color: transparent; ">/usr/local/mysql.

Create my.cnf file
To complete MySQL server installation, you have to create a configuration file. It offers several security and control options (here you can limit system resources to be used by MySQL server, set the default collation and character set etc.). You need not to create a brand new configuration file – there are 4 pre-made files in the support-files/ directory. Read the information in those files to determine which one to use. For small servers (e.g. testing servers, or servers of a limited performance), my-small.cnf file is the best option. Copy the file of your choice to /etc/my.cnf : cp support-files/my-small.cnf /etc/my.cnf chown root /etc/my.cnf chgrp root /etc/my.cnf chmod 644 /etc/my.cnf We have made sure both the owner and user group of the my.cnf file are “root” and the access privileges are properly set. Finally edit the file: vi /etc/my.cnf Search for [mysqld] clause, and add immediately below it: user = mysql We have specified that MySQL service is to be run with user “mysql” privileges. If you want to use InnoDB databases (what you probably will), uncomment (and perhaps edit) all innodb options in the my.cnf file. Save all changes.

Additional settings
For proper functioning, MySQL needs a “mysql” database. To create this database, simply run: /usr/local/mysql/bin/mysql_install_db --user=mysql The script will create /usr/local/mysql/var/ directory containing the necessary databases. This directory serves as a default storage for all databases you will create. Make sure it is writable by “mysql” system user!

Start server, check it, connect
Now you are ready to start your MySQL server for the first time. /usr/local/mysql/bin/mysqld_safe --user=mysql & Hit enter again to get your prompt back. The MySQL server should now be running. To check that server is running and works properly enter /usr/local/mysql/bin/mysqladmin version <p style="margin-top: 0.5em; margin-bottom: 0px; border-style: initial; border-color: initial; outline-width: 0px; outline-style: initial; outline-color: initial; font-size: 14px; background-image: initial; background-attachment: initial; background-origin: initial; background-clip: initial; text-align: left; color: rgb(38, 50, 72); font-family: DINPro, Verdana, Arial, sans-serif; font-style: normal; line-height: 19px;">You should get some response about the server software version.

Connect to MySQL server: /usr/local/mysql/bin/mysql -u root If you get a welcome message and the prompt changes to mysql>, the server works and everything is fine. If this failed for any reason, it may indicate some problems with your installation/configuration.

Set the root password
Now, before you do anything else, set root user’s password (!). Stay connected to MySQL and enter: DELETE FROM mysql.user WHERE User = ; FLUSH PRIVILEGES; SELECT Host, User FROM mysql.user; Look for the record that has root in the User column and something other than localhost in the Host column. This is the host_name. SET PASSWORD FOR 'root'@'localhost' = PASSWORD('new_password'); SET PASSWORD FOR 'root'@'host_name' =  PASSWORD('new_password'); Remember, this is the MySQL superuser for all databases. Therefore you should use a strong password and keep it safe. Later, when you will be writing PHP scripts, do NOT use superuser for accessing databases! The “root” user is meant only for administration purposes. After you are finished, exit MySQL: quit

Restart MySQL server
After everything is set up, restart MySQL server: /usr/local/mysql/bin/mysqladmin -u root -p shutdown /usr/local/mysql/bin/mysqld_safe --user=mysql & Voila, your MySQL server is up and running. Last Installations Commands While in your Ruby On Rails source code directory, type in the following commands to configure the database and finalize the ThBook System installation : rake db:create rake db:migrate rake db:fixture:load

That's it. The application should now be fully functionnal. You can see the home page just by typing your application server name on a web browser.