Rails Deploy

Overview

Deploying Ruby on Rails is done using Capistrano (on Github), a Ruby tool for specifying deploy tasks, and allowing rollbacks.

Requirements

SSH access

You will need ssh access to the OCF apphost server. Refer to internal documentation (prot) for getting access.

You also need SSH access to Github.

Github access

The deploy will always download the latest commit on the master branch of the compserv/hkn-rails repo. Ask another officer for push access.

Ruby

The required Ruby version is specified in Gemfile. This version of Ruby must be installed on your system; RVM is highly recommended to install multiple versions of Ruby simultaneously.

Ruby dependencies

Capistrano is a Ruby tool, with various extra dependencies specified in the Gemfile. You must install these using Bundler, by opening a shell in the hkn-rails repo and running:

bundle install

Deploy

To deploy, open a shell in your local copy of the hkn-rails repo.

First push your changes to the main repository (here, named compserv, this may differ from your fork on 'origin')

$ git push compserv master

Then (assuming your dependencies have been installed with run Capistrano:

$ bundle exec cap production deploy

You may be prompted for your SSH key password, if you added one (recommended, but not necessary).

The five parts of this command are:

• bundle: a Ruby environment manager, similar to pipenv. Installs dependency gems (libraries).
• exec: executes a command in the Ruby environment for this project. This gives access to installed gems.
• cap: the Capistrano command-line tool.
• production: a specific target environment, specified in config/environments.
• deploy: The Capistrano deploy task.

This command will roughly execute the following:

1. Create a release folder for this deploy, named by timestamp (YYYYMMDDHHMMSS)
2. Download the master branch of compserv/hkn-rails
3. Install fresh dependencies
4. Restart the web server (with systemd)
5. Restart solr, a search indexing program

Rollback

If somehow the deploy fails, or the deployed code broken, the deploy may be rolled back to an earlier one:

$ bundle exec cap production deploy:rollback

By default, this will rollback to the very last release. You may specify a specific release timestamp as an extra argument:

$ bundle exec cap production deploy:rollback ROLLBACK_RELEASE=release

Currently Capistrano is configured to store 5 past releases on the apphost server, removing them when there are too many.

Github rollback

If you have no good deploys on the server, or if the rollback task fails, you may revert the commits on Github, and instead deploy a new release:

git revert <commit>...
bundle exec cap production deploy

Deploy layout

Capistrano deploys releases in a very structured layout on the apphost server:

~/hkn-rails/
    prod/
        current@ -> (symlink to current release)
        releases/
            20181107221905/ (copy of repo)
            ...
        repo/
        shared/
            ... (assets)
    migrate/
        current@ ->
        releases/
        repo/
        shared/

This is configurable in config/deploy.rb or config/deploy/*.rb.

Troubleshooting

TODO