Skip to content
This repository

Installation and Deployment

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 at least Ansible 1.3, which (as of September 8, 2013) is only available via Git. You can see instructions for how to run a development version of Ansible on their website. Arch Linux users can install the ansible-git package from the AUR.

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 6
  • 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 https://github.com/cpence/rletters-ansible.git
cd rletters-ansible

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.

Deploy

Execute

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. NOTE: Because of a bug in Ansible, if these passwords contain a colon (':'), it is replaced by an underscore in the password on the server (but not in the file on disk).

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 admin@example.com and password. You should now change this default username and password. Under the "Users" menu, click "Admin Users." Press the "New Admin User" button in the top right corner. Fill out the e-mail, and provide a password. Click "Log Out" at the top right, and log in as the new user. Once again, go to "Admin Users" in the "Users" menu. At the far right of the row for the user "admin@example.com", click "Delete." Click "OK" in the confirmation box.

Configure Server Settings

Now that you've secured the administration panel, click "Settings." Fill out the settings on this page as suits your application:

  • Application Name: The user-friendly name of your application.
  • Contact E-mail: The e-mail address to which bug reports, cron job output, and other development chatter should be sent.
  • Application Domain Name: The domain name at which your application is published.
  • Solr URL: This URL should have been automatically configured by the deployment scripts, and so should not need to be changed.
  • Solr Timeout (sec): The timeout for Solr reads, in seconds (120 is the default value).
  • Mendeley Consumer Key: If you would like your users to be able to search for document results on Mendeley, you will need to visit the Mendeley Developers Portal and register your application.
  • Airbrake API Key: If you have an Airbrake account, this is your Airbrake API key (available under "Edit this Project" in the Airbrake main window).
  • Google Analytics Tracking ID: RLetters can automatically add the Google Analytics page-tracking code to every page of your site, if you fill in your ID here (which will be something like UA-12345678-9).
  • jQuery Mobile Theme CSS: If you would like to create a custom jQuery theme for your site, you may do so here, and paste the CSS directly into this setting. It will automatically be added to every page.

Customization

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.

Maintenance

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.

Troubleshooting

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 http://192.168.111.222. 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 admin@example.com administration user. If, however, the state of your database becomes corrupted and you need to rebuild, this command will accomplish that.

Something went wrong with that request. Please try again.