Orchestration

Overview

Orchestration provides a toolkit for building and launching Rails applications and dependencies in Docker.

A suite of tools is provided to assist in creating configuration files, launching service dependencies, verifying that dependencies have launched successfully (e.g. for running tests in contiuous integration tools), and building, tagging, and pushing Docker images.

Containers are automatically created for the following dependencies:

  • MySQL
  • MongoDB
  • PostgreSQL
  • RabbitMQ

Installation

Add this line to your application's Gemfile:

gem 'orchestration', '~> 0.2.0'

And then build your bundle:

$ bundle install

Usage

Generating configuration files

A Rake task is provided to generate the following files:

  • Makefile - provides easy access to all Orchestration utilities.
  • .gitignore - ensures any unwanted files created by Orchestration do not clutter your project's version control system.
  • docker/Dockerfile - a ready-to-use Docker build script which should need minimal (if any) modification to build your Rails project.
  • docker-compose.yml - a custom-made set of services to allow you to run your application's dependencies locally.
  • .orchestration.yml - Orchestration internal configuration, e.g. Docker username.

Building and pushing your project as a Docker image

Private Git repository authentication

If your project has any dependencies on private Git repositories then you will need to create an authentication token. See the relevant documentation for your Git host:

Create a file named .env in the same directory as your docker-compose.yml and add one or both of the following (note that Bitbucket and GitHub use a different format):

BUNDLE_BITBUCKET__ORG=<bitbucket-username>:<app-password>
BUNDLE_GITHUB__COM=x-oauth-basic:<auth-token>

Docker installation

Docker must be installed on your system. See the Docker getting started guide for instructions.

DockerHub account

You will need an account with Docker Hub (or your preferred Docker image host) to push your images. Visit the Docker Hub webpage to sign up, then run the following command and enter your credentials when prompted to log in to your new account:

$ docker login

Using provided Makefile

To build and push your image run:

$ make docker

Or run the two steps separately:

$ make docker-build
$ make docker-push

Starting and waiting for services when running your tests

To start services:

$ make start

This will launch any dependencies your project needs (e.g. MySQL, MongoDB, etc.).

To wait for all services to be ready:

$ make wait

It is recommended that you create a test command in your Makefile which will launch all dependencies and wait for them to be ready before running all tests. For example:

test: start wait
    bundle exec rspec
    yarn test app/javascript
    bundle exec rubocop
    yarn run eslint app/javascript

This is especially useful for continuous integration as it provides a uniform command (make test) that can be run by your CI tool without any extra setup.