This gem provides a DSL for creating docker containers for running a family of Rails apps.

Code Climate Test Coverage Build Status


  1. Install Docker
  2. Install ruby and the ruby_yacht gem.


Create a file called run.rb, which will be the main file for your docker scripts. This file can be called anything, but we will use that name here so we have a consistent reference.

Enter this in the file:

    require 'ruby_yacht'

    RubyYacht.configure do

Your run.rb file will have two parts: A configuration block and the Runner command. The configuration block defines your projects and your apps. You can read the configuration documentation for more information on the configuration options.

The runner command invokes a RubyYacht script based on the command information.

RubyYacht Scripts

RubyYacht provides several scripts to build and manage your application environment. You can invoke these scripts by calling ruby run.rb [command].

The examples below describe the results for the projects in the configuration sample file, which contains the following projects:

  • Project: apollo

    • apps: mars, saturn
    • database: localhost
    • domain: apollo.docker.local
  • Project: jupiter

    • apps: venus, saturn
    • database:
    • domain: jupiter.docker.local


This command lists available commands, and provides information on the syntax and options for each command.


This command builds images for your projects, runs the containers, and updates your hosts file to add entries that point your app's domains toward the local docker address. This is a combination of build_images, run_containers, and update_hosts, so you can run those commands individually, and in different combinations, if you prefer.


This command builds all of the images for your project. For the example above, it will build the following images:

apollo-app-dependencies An image with mars and saturn checked out, and all of their dependencies installed
apollo-database An image with mysql installed and a database set up with the schema and seeds from mars and saturn
apollo-mars An image with the mars app installed, and the dependencies for mars installed, set up to point to the apollo-database database.
apollo-saturn An image with the saturn app installed, and the dependencies for saturn installed, set up to point to the apollo-database database.
jupiter-app-dependencies An image with venus and saturn checked out, and all of their dependencies installed
jupiter-venus An image with the venus app installed, and the dependencies for mars installed, set up to point to the database.
jupiter-saturn An image with the saturn app installed, and the dependencies for saturn installed, set up to point to the database.
apollo-web An image with nginx installed, and set up to proxy the app containers for apollo-mars, apollo-saturn, jupiter-venus, and jupiter-saturn. Each app will get a subdomain of the project's main domain, with the subdomain named after the app.


This command runs all of the containers for the images described above. Each container will have the same name as its image. Each container will be on a docker network called apollo, and will have network aliases corresponding to the container names. For instance, the apollo-web container will be able to access the apollo-mars container under the hostname apollo-mars. The apps will also be able to talk to each other using these network aliases.

It will not run a container for the app-dependencies images. Those images are intended to use as a baseline for the app and database images, to reduce their build times.

All of the containers will be run as daemons.


This command updates your hosts file to add entries for your containers. This is intended to help with development environments, where you won't have a real domain that resolves to your local machine.

For the examples above, it will add entries for these domains:

  • apollo.docker.local
  • mars.apollo.docker.local
  • saturn.apollo.docker.local
  • jupiter.docker.local
  • venus.jupiter.docker.local
  • saturn.jupiter.docker.local

This will allow you to access your local version of the apps in the web browser on your local machine without any additional DNS setup.

Before overwriting the hosts file, it will save a copy of the existing hosts file to /etc/hosts.{timestamp}.backup.

This will prompt you for your password, because it needs root privileges to update the hosts file. It will only use that privilege to run the commands:

    sudo cp /etc/hosts /ect/hosts.{timestamp}.backup
    sudo cp tmp/hosts /etc/hosts

The tmp/hosts file is populated prior to the privilege escalation with the updated hosts file contents.


This will remove all of the containers and images for your projects, and also remove any dangling docker images. After this is done, you can run the build command to rebuild your environment from scratch.

This will not ruby the ruby and nginx images. Those are downloaded as part of the build process, and are provided by third parties as official docker images for those ruby and nginx.


This allows you to start, stop, or restart containers. If you run it with the start sub-command, it will also start docker-machine, if necessary. The most common use case for this is to run ruby run.rb services start after you reboot your machine, to get your docker environment up and running again.


This opens a shell in an app container. By default, this opens a bash shell, but any additional commands you pass it will be forwarded to the container and run.

For instance, you can run ruby run.rb shell mars to open a bash shell in the mars app container, or ruby run.rb shell mars rails c to open a rails console, or ruby run.rb shell mars tail -f log/development.log to start reading all the content printed to the development log file.


This checks out a new branch inside an app container, and restarts the app container. It will also immediately run any database migrations from the new branch.

If you run it for a branch that you already have checked out, it will pull down the latest changes from the repository.

Plugins and Customization

RubyYacht has a plugin API for customizing the behavior of your scripts. You can use plugins for defining new app types or database types, or for adding hooks for the built-in types. This plugin API is so powerful that all of the rails-specific and mysql-specific code in RubyYacht is provided through plugins.

Additional Information

If you're interested in contributing to the project, you can find more information in the contributing documentation. You can also reach out to me on Twitter @brownleej