One of the most compelling reasons to use Ruby on Rails is the ease in which you can get a web project up and running. And one of Docker's key benefits is freedom from "dependency hell”. In his prior post, Mike Arnold (@dharmamike) provided a 5-Step guide on how to setup In-container Rails development on your local machine using Docker Compose.

After over a year of developing with Docker and Rails, the Labs team wanted an easier method for creating Docker-ready Rails projects. That was the genesis behind the gem now available on Github, Flatcar. Flatcar provides a single CLI command that sets up a Rails development environment with data volume and persistent database support, enabling you to use your preferred IDEs or other dev tools, while including just the application code in the final container build.

Installation and Dependencies

First, You must have Ruby installed on your machine to install Flatcar. The Ruby installation steps can vary between Linux, Windows or Mac, but this is a great place to get get started. One recommendation is to use a version manager like rbenv or RVM.

Personally, I prefer rbenv, but both have large fan bases. Provided you have Ruby installed, you also have Docker and Docker Compose on your machine in order for Flatcar to work. If you are on Linux, install Docker with official packages. On a Mac or Windows, you will need to run a lightweight VM in order to use Docker. You can do this via Docker Toolbox or by running a VM of your choice.

If you haven't yet made the switch from boot2docker to docker-machine, now would be a good time. Although Flatcar will work with any VM, Docker Machine is easy to use and with a shallow learning curve. Once you've got your system setup, run gem install flatcar and you're ready to get rolling.



Creating a new Rails project (Recommended)

From the desired parent directory, run flatcar init $new_project_name. This will initialize a new Rails application in a directory of the same name.

Using an existing Rails project

For existing Rails projects, run flatcar init $path_to_project to begin a new project. You can also initialize a flatcar project from the current directory by simply running flatcar init. (Keep in mind that Flatcar only works with the simplest of existing Rails projects, and will likely not work "as is" for projects more complex that a basic web front-end and database app).

flatcar init ($new_project_name|$path_to_project) will perform the following operations: 1. If no project path is specified, it runs rails new -B $app_path. 2. Flatcar generates a Dockerfile for the Rails service 3. A docker-compose.yml file is generated for the entire project.

Flatcar applications are run via docker-compose in the project's directory. If you're using a VM, make sure to create appropriate port forwarding rules in order to view the application in your browser. Flatcar will bind 3000:3000 from host:container via Docker's -p flag at runtime.

To run the application, cd into the project directory and run docker-compose up. To run the services in the background, use the -d flag.


Flatcar uses the following syntax: flatcar [global options] init [command options] [APP_NAME]

The init command initializes a Rails application with an optional base image and database specified. If executed within an existing Rails project directory without the APP_NAME argument, the Flatcar-generated files will be placed in the current directory. If the command is executed with the optional APP_NAME argument, a new Rails project will be generated along with the Flatcar files in a subdirectory of the current directory.

Selecting a base image

You can specify which OS to use for your Rails service by passing in the -b flag. Valid options are alpine, ubuntu, or rails (debian-based). If no option is given, the default Rails image will be used.

Choosing a database

You can also specify which database to use with your Rails application using the -d flag. Valid options are mysql, postgresql, or sqlite3. If mysql or postgresql is chosen, a new database service will be defined in the generated docker-compose.yml file. If no option is given, the default sqlite3 will be used.

Additional Command Options

Besides specifying the base image or database, Flatcar also supports a variety of other configuration options, such as not including Sprockets files, using a specified Javascript library, or ignoring source control .keep files.

See the Flatcar for the full set of command options.


We hope you find this tool helpful for quickly getting started with Docker-ready, Ruby on Rails projects. Of course we welcome community contribution. If you have ideas on how to improve Flatcar, community feedback is welcome via Github or simply submit your PR.