Production Deployment

General Warning

• Copy and run each command individually. Don't copy bulk of commands and paste them. Because if you do bulk copy/paste - even if the first command fails, the second will start running and cause problems
• Read the output of each command and make sure its successful before running the next. If you're not sure whether a command passed or failed, a good way is to check whether the exit code (echo $?) is 0

Setting up the web server

• We support Ubuntu 12.04
• Make sure you add a separate admin user:

sudo adduser admin

• Install the following core software:

sudo apt-get -y update
sudo apt-get -y install python-software-properties libxml2-dev libxslt1-dev build-essential git openjdk-7-jdk imagemagick openssh-server zlib1g-dev

• Install latest CouchDB (1.3.x) from a PPA:

sudo apt-add-repository -y ppa:nilya/couchdb-1.3
sudo apt-get -y update
sudo apt-get -y install couchdb

• Install Ruby 1.9 and Nginx from a PPA:

sudo apt-add-repository -y ppa:brightbox/ruby-ng
sudo apt-get -y update
sudo apt-get -y install nginx-full ruby1.9.3 passenger-common1.9

• Make sure all Ruby gems don't install unnecessary documentation:

echo "gem: --no-ri --no-rdoc" | sudo tee -a /etc/gemrc

• Install Bundler

sudo gem install bundler -v "1.3.5"

• Make sure nginx configuration is writable by admin:

sudo chown admin:admin /srv
sudo chown admin:admin /etc/nginx/sites-enabled

• Edit nginx configuration: sudo vim /etc/nginx/nginx.conf And make the following changes:
  • Enable passenger for ruby by uncommenting the following lines under http { section:

  passenger_root /usr/lib/phusion-passenger;
  passenger_ruby /usr/bin/ruby;
  

  • Add a server certificate under http { section:

  ssl_certificate <</full/path/to/server_cert.pem>>;
  ssl_certificate_key <</full/path/to/server_key.pem>>;
  ssl_session_timeout  5m;
  ssl_protocols  SSLv2 SSLv3 TLSv1;
  ssl_ciphers  ALL:!kEDH!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
  ssl_prefer_server_ciphers   on;
  

  NOTE: If you don't have a proper certificate, then you can generate a local certificate for temporary use. Follow the Nginx SSL guide.
  • Save the file and restart nginx:

  sudo /etc/init.d/nginx restart
  

• Edit CouchDB file:

sudo vim /etc/couchdb/local.ini

And make the following changes:

• Make CouchDB listen on 0.0.0.0 for server-to-server replication.

# Change:
;bind_address = 127.0.0.1
# To:
bind_address = 0.0.0.0

• Make CouchDB use SSL:

[daemons]
# Make sure below line is present and NOT commented:
httpsd = {couch_httpd, start_link, [https]}

[ssl]
cert_file = <</full/path/to/server_cert.pem>>
key_file = <</full/path/to/server_key.pem>>

• Add an administrator account:

[couch_httpd_auth]
# Make sure the below line is present and NOT commented:
require_valid_user = true

[admins]
<<admin-username> = <<admin-password>>
# This password will get automatically salted and hashed by CouchDB

• Save the file and restart couchdb:

sudo /etc/init.d/couchdb restart

• Enable CouchDB over firewall:

sudo ufw allow 5984
sudo ufw allow 6984

NOTE: In case of self-signed certificates, it needs to be added to the RapidFTR---Android code.

• Copy the public key and add it to rapidftr-android/res/raw.
• Modify the pom.xml[RapidFTR---Android/RapidFTR-Android/pom] file, add another with the pointing to the public key certificate created earlier.
• This step is unnecessary if wildcard certificates are acquired for rapidftr.com

Deploying to the Web Server

• Checkout the LATEST RapidFTR code (either in your local machine, or in the CI). We always need the LATEST codebase to perform the deployment, even if you're deploying older releases.
• Run this command to perform the deployment:

cap 
  -S deploy_server=<server name or IP address>
  -S deploy_user=<user name to login to the server>
  -S server_name=<DNS name which is used by end users to access the server>
  -S rails_env=production 
  -S http_port=80 
  -S https_port=443 
  -S solr_port=8983 
  -S couchdb_host=localhost
  -S couchdb_username=<username for couchdb>
  -S couchdb_password=<password for couchdb>
  -S nginx_site_conf=<path to nginx "sites-enabled" folder, e.g. /etc/nginx/sites-enabled>
  -S branch=<branch that you want to deploy, like release1 or master>
deploy

• After deploying, you may need to restart nginx once, specially if its a first time deployment:

sudo /etc/init.d/nginx restart

Directory Structure after Deployment

A clear and standard directory structure will be created in the target Web Server for every deployment:

• /srv/rapid_ftr_production/
  • releases/ - this contains all the releases done so far
  • current/ - symlink to releases/
    • log/ - symlink to shared/log
  • shared/
    • log/ - log files for the current release, these will never be overwritten during any release
      • server.log - Nginx HTTP server access logs
      • error.log - Nginx HTTP server error logs
      • production.log - Logs from the RapidFTR rails application
      • rapidftr-scheduler.output - Scheduler log
    • bundle/ - all shared ruby gems used for by RapidFTR

Deploying multiple instances on same server

It is easily possible to deploy multiple instances of RapidFTR in the same server. You only have to modify three parameters for each instance: Domain Name, RAILS_ENV and solr_port.

• See the Deploying to the Web Server section above for basic deployment instructions
• Now, to deploy multiple instances on the same server, change the server_name, rails_env and solr_port parameters for each instance.
• Example scenario:
  • First instance (for example - uganda.rapidftr.com):

    cap 
      -S deploy_server=<server name or IP address>
      -S deploy_user=<user name to login to the server>
    
      -S server_name=uganda.rapidftr.com 
      -S rails_env=uganda 
      -S solr_port=8983 
      ....
      ....
      deploy
    

  • Second instance (for example - sudan.rapidftr.com):

    cap 
      -S deploy_server=<SAME SERVER>
      -S deploy_user=<SAME USER>
    
      -S server_name=sudan.rapidftr.com 
      -S rails_env=sudan 
      -S solr_port=8984
    
      ....
      ....
      deploy
    

• Note: When giving rails_env - please do not use the following reserved names. Your deployed instance will not function properly if you use any of these: test uat android cucumber standalone development
• Note 2: You may want to create different CouchDB username/password for each instance, but that is not mandatory. Check the Edit CouchDB file instructions at the top, it has instructions for one admin user, and you can create another user in the same way.