Installation and Deployment

Charles Pence edited this page Jan 27, 2016 · 22 revisions

This guide will show you how to install and configure a basic RLetters server using our Ansible scripts. As a bonus, the Ansible scripts are all human readable, so you can duplicate all these steps on your own if you'd like.

Install a recent version of Ansible

You need a current version of Ansible. We're currently testing on Ansible 2.0, so we know that it works. Some earlier versions might as well, but we don't carefully keep track of the versioning of the Ansible API calls that we use.

Configure a server or cluster

RLetters supports being automatically provisioned to a single server, or to a cluster. (Cluster deployments have not been extensively tested; please get in touch if you successfully run one!) For a cluster deployment, the following roles can be separated to independent servers if you'd like:

  • Solr server, running the search and document-storage backend (maximum of 1 server, Solr clustering not supported)
  • Database server (maximum of 1 server, database sharding/replication not supported)
  • Redis server (maximum of 1 server, master/slave replication not supported)
  • Web servers (no limit, all connecting to the same database/Solr backend/Redis server)

Each of these machines needs to have the following configured:

  • RHEL or CentOS 7
  • Password-less SSH access from your development machine to a non-root user (using an SSH key file)
  • Password-less sudo for all commands for this non-root user

This will allow Ansible to connect to and fully provision your server without any user input.

Get the deployment scripts

Now, check out a copy of our deployment scripts, which are hosted in a separate GitHub repository.

git clone
cd ansible-playbook

Configure server locations

Next, set up the locations of your servers you configured above.

cp hosts.example hosts
$EDITOR hosts

This should be a fairly obvious file to configure; see the documentation from Ansible on the inventory file if you need complex configuration such as SSH usernames or ports.

To make sure that Ansible is properly installed and can communicate with your servers, issue the command

ansible -i hosts all -m ping

You should see a successful "pong" response from each of your servers. If so, you're ready for deployment.



ansible-playbook -i hosts site.yml

This will install and configure RLetters on your server cluster.

In the process, several accounts and passwords will be created and stored in your development tree:

  • On the database server, a PostgreSQL database user is created. The username is rletters_postgresql, and the password can be found in roles/db/files/db_${host}_pass.
  • On the Solr server, an administration user for the Tomcat administration GUI is created. The username is rletters_tomcat, and the password can be found in roles/solr/files/tomcat_${host}_pass.
  • On each of the web servers, a deployment user is created, which has ownership of the RLetters installation directory and is the user that the web server will run as. The username is rletters_deploy, and the passwords can be found in roles/web/files/deploy_${host}_pass.

Edit the environment file

The deployment procedure has created a basic file of static site settings for you to edit, which will be located at /opt/rletters/root/.env. SSH to your server, open the file, and configure these settings to your liking, rebooting when finished. Documentation on the available settings and their effects is included within the file. Note that you do not need to configure the following variables, as they will have been set by the deployment scripts:

  • the secret tokens at the bottom of the file

Secure Administration Panel

THIS STEP IS VITALLY IMPORTANT. You should now log in to the administration panel for your site, at http://YOUR_SITE_URL/admin. Log into the administration panel using the default username and password of and password. You should now change this default username and password. Under the "Accounts" menu, click "Administrators." Create a new administrator using the interface, providing an e-mail and password. Click "Log Out" at the top right, and log in as the new user. Once again, go to "Administrators" in the "Accpimts" menu. At the far right of the row for the user "", click "Delete." Click "OK" in the confirmation box.


The only thing remaining is to customize some static content that is shipped with RLetters. All of this is also done via the administration console.

  • Settings -> Custom Pages: This is customized text that should be changed for your site. You can edit these using full Markdown syntax, and some embedded Ruby code is usable.
    • Privacy Notice (short and full): We've filled this in with a pretty good default privacy policy for the default settings of RLetters. If you change the way that you interact with your users, you should update this privacy policy.
    • About: A general "about this application" page for your application.
    • FAQ: A page of frequently asked questions for your application. This file ships with a few default questions that users are likely to ask about the framework in general.
    • Tutorial: A tutorial that introduces your application to users. A nice tutorial would show users how the search and datasets pages work, and then provide a few examples of searches and analyses that provide interesting results.
  • Settings -> Custom Assets: These are custom images and other static assets that can be branded for your site:
    • Splash Screen (768x1004): displayed while loading the app on retina-display iPhone devices.
    • Splash Screen (320x460): displayed while loading the app on low-resolution iPhone and iPod Touch devices.
    • Favorite Icon (16x16): the standard favorite icon.
    • Error Page Watermark: This is an image shown in the bottom-left corner of the site's error pages. Something like 500x300 pixels is a good size for this image.
    • App Icon (WxH): The various app icons, used on (depending on resolution) the iPhone, iPod Touch, iPad, or Retina-display iPhone/iPad.

That's it! You've successfully configured a new RLetters installation, and even personalized it a bit to make it your own.


Upgrading RLetters

To upgrade the version of RLetters on your deployment, you can execute:

ansible-playbook -i hosts site.yml --tags rletters

This will execute an upgrade of the RLetters code and perform a no-downtime rolling restart. If there are pending database migrations, you can execute:

ansible-playbook -i hosts site.yml --tags rletters,rletters_migrate

This will cause some downtime, however, as some database queries may begin to fail until the application code has been refreshed.


Running under a virtual machine

If you would like to run RLetters under a virtual machine -- or, alternatively, if you would like to run the unit tests for the deployment process -- then you need to do the following.

  • Install Vagrant, from their website or your package manager.
  • Install sshpass so that Ansible can connect "passwordless" to the Vagrant box without a public key.
  • Execute rake download in the rletters-ansible directory to download and install the Vagrant box on which we'll provision RLetters.

To run the deployment tests, you can then execute bundle and rspec, which will spin up a full installation of RLetters, execute some tests to make sure it's working correctly, and then break it back down again. NOTE: This test takes a long time, around half an hour on my development machine.

To run RLetters in a virtual machine, you can execute:

rake up
ansible-playbook -i hosts.testing site.yml

There will now be a test installation of RLetters running inside a virtual machine, accessible at You can configure the Vagrantfile in the root of the source tree to have more control over the local virtual machine.

Rebuilding the database

If you have the need to re-seed the database, you can execute:

ansible-playbook -i hosts site.yml --tags rletters,rletters_migrate,rletters_seed

In general, this command should not be executed, as the seeding process will (1) replace all of your customizations to custom pages and custom assets, and (2) re-create the unsecure administration user. If, however, the state of your database becomes corrupted and you need to rebuild, this command will accomplish that.

SSH host key errors on a virtual machine

If you're running under a Vagrant VM, you may have trouble with Ansible's host key checking feature. To disable this, edit your ~/.ansible.cfg file and add:

host_key_checking = False

NOTE: You should disable this when working on remote servers, to prevent man-in-the-middle attacks!