Revision as of 13:47, 1 March 2011

Overview

Running and deploying QA Reports relies heavily on automated deployment scripts and version control repository. At high level, deployment process is following:

1. Log in to your workstation and update QA Reports working tree
2. Run Capistrano deployment script on your workstation
3. Capistrano script connects to the production server and updates the deployment by
   1. Connecting to version control system from production server and updating the source code on the production server
   2. Running the migrations and updating the database schema on production server
   3. Restarting the application on production server

Capistrano enables you to automate also other administrative tasks like

1. Rolling back to previous deployment
2. Exporting data from production environment to your development environment

To achieve all the goodness, you should set up the development environment on your workstation before continuing.

Setting up the production server

This guide has been written for vanilla Ubuntu 10.04 installation. You need to be logged in to the production server and have sudo rights to continue.

Install dependencies

$ sudo aptitude install curl build-essential git-core openssh-server zlib1g-dev libssl-dev libreadline5-dev libcurl4-openssl-dev

Install Ruby

1. Install Ruby Version Manager (using system-wide installation script)
   $ sudo bash < <( curl -L http://bit.ly/rvm-install-system-wide )
2. Set up .bashrc as instructed by RVM installer: The whole content into an if section, and after that loading of RVM. Here's an example .bashrc
3. Run: $ source ~/.bashrc
4. Add your account and the deployment account to rvm group, e.g.
   $ sudo adduser jakeskik rvm
5. Source your .bashrc to enable rvm
   $ source ~/.bashrc
6. Install Ruby Enterprise Edition
   $ rvm install ree
7. Set the default Ruby interpreter
   $ rvm use --default ree
8. Install bundler
   $ gem install rails bundler --no-ri --no-rdoc #if you have proxy problem, plz refer to http://docs.rubygems.org/read/chapter/13#page51

Finally, enable rvm and Ruby Enterprise Edition to your deployment account, e.g. www-data

1. Edit /etc/passwd and change www-data's shell from sh to bash. You might want to change the home directory also from /var/www to e.g. /home/www-data as shown below
   www-data:x:33:33:www-data:/home/www-data:/bin/bash
2. Enable RVM as shown below

 $ sudo adduser www-data rvm
 $ sudo -iu www-data
 $ cp ~jakeskik/.profile .
 $ cp ~jakeskik/.bashrc .
 $ exit

Install Apache and Phusion Passenger

 $ sudo apt-get install apache2 apache2-prefork-dev libapr1-dev libaprutil1-dev
 $ gem install passenger --no-ri --no-rdoc
 $ rvmsudo passenger-install-apache2-module # Follow the on-screen instructions and edit apache.conf
 $ sudo service apache2 restart

Install MySQL

 $ sudo apt-get install mysql-server libmysqlclient-dev

Install Postfix

QA Reports sends email notifications for system administrators (you) in case the application throws an exception. To enable notifications, there needs to be a mail server configured on the production host.

 $ sudo apt-get install postfix

The default configuration is fine and allows only delivery for emails originated from localhost. Just click through the installer.

Test the environment

After installing the software, run a sanity check for the environment by creating a 'hello world' rails project and corresponding virtual host:

$ sudo -iu www-data
$ rails new hello
$ cd hello/public && pwd
/home/www-data/hello/public
$ exit

Write a following virtual host declaration to /etc/apache/sites-available/hello:

  <VirtualHost *:80>
     ServerName hello.qa.leonidasoy.fi
     DocumentRoot /home/www-data/hello/public
 
     <Directory /home/www-data/hello/public>
        AllowOverride all
        Options -MultiViews
     </Directory>
  </VirtualHost> 

Enable the virtual host

 $ sudo a2ensite hello
 $ sudo service apache2 restart

Add the virtual host to /etc/hosts file:

 127.0.0.1 hello.qa.leonidasoy.fi # Use the same domain as above

Now you should be able to access the 'hello world' project with a browser, e.g. lynx

 $ lynx hello.qa.leonidasoy.fi

Create a database for QA Reports

$ mysql -u root -p
mysql> create user 'qa-reports'@'localhost' identified by 'somepasswordofyourchoosing';
mysql> create database qa_reports_production character set 'utf8';
mysql> grant all privileges on qa_reports_production.* to 'qa-reports'@'localhost';
mysql> flush privileges;
mysql> exit

Create virtual host for QA Reports

Write a following virtual host declaration to /etc/apache/sites-available/qa-reports:

  <VirtualHost *:80>
     ServerName qa-reports.qa.leonidasoy.fi
     DocumentRoot /home/www-data/qa-reports.meego.com/current/public
 
     <Directory /home/www-data/qa-reports.meego.com/current/public>
        AllowOverride all
        Options -MultiViews
     </Directory>
  </VirtualHost> 

Enable the virtual host

 $ sudo a2ensite qa-reports
 $ sudo service apache2 restart # Don't mind the warning about missing dir,
                                # we'll deal with that one in a sec

Deploying QA Reports

QA Reports uses Capistrano to automate the deployments. The main benefit is to eliminate the risks of human errors and to enable easy and repeatable rollbacks. See Capistrano documentation for the details.

Capistrano is run from your development environment, so you should be now on your workstation with working QA Reports development environment to continue.

Enable public key authentication for your deployment account

Set up public key authentication:

1. Generate yourself as SSH key pair if you don't have one: $ ssh-keygen
2. Add your public key to authorized_keys file of your production environment user:
   $ ssh your.production.user@your.production.host 'mkdir .ssh; echo '`cat ~/.ssh/id_rsa.pub`' >> ~/.ssh/authorized_keys'
3. Try logging in: ssh your.production.user@your.production.host

Modify Capistrano scripts and deploy QA Reports

QA Reports uses following scripts to configure Capistrano

• config/deploy.rb
• config/deploy/staging.rb
• config/deploy/production.rb

You might want to review all the files, but usually it's enough to update only config/deploy/production.rb according to your needs (servers, deployment account, ssh options). You can also create new deployment environment just by copying the production.rb, to e.g. internal.rb and modify it.

Once the Capistrano is updated according to your needs, run

 $ cap production deploy:setup # or cap internal deploy:setup, if you created a new deployment environment

Setup command creates the folder hierarchy and the symbolic links required by Capistrano. During the setup it requests following information

1. Database host
2. Database port
3. Database name
4. Database username
5. Database password
6. Should QA Reports send performance data to NewRelic? (Default: no)
7. Registration token. This will be part of the registration url, e.g. foobar will make registration to be at url /users/foobar/register
8. Email addresses for Exception Notifier

Once the setup is complete, the deployment is as easy as it gets

$ cap production deploy:migrations

You should now have QA Reports up&running. Congrats!

Update QA Reports to a new version

1. git pull (In case there's changes in the deployment scripts)
2. cap production deploy:migrations
3. Ta-da!

Roll back to previous version

1. cap production deploy:rollback
2. Ta-da!

Setting Up the Production Environment with nginx instead of Apache

1. Follow instructions above until "Install Apache and Passenger", then continue here from step 2.
2. Install passenger: $ gem install passenger
3. Install nginx: $ passenger-install-nginx-module
   1. Notice: the default location is under /opt. If you wish to install there, use rvmsudo. Notice however, that part of your ~/.rvm contents will then belong to root and may cause gray hair later. I chose to install under ~/nginx.

Edit nginx configuration installation_path/conf/nginx.conf:

1. 1. Comment out section location / { ... }
   2. Add lines:
      1. passenger_enabled on;
      2. root /home/your_prod_env_user/qa-reports.meego.com/current/public;
2. Start nginx: $ sudo /installation_path/sbin/nginx
3. Continue with the guide above from "Deploying QA Reports"