Quickstart: Compose and Rails

Estimated reading time: 7 minutes

This Quickstart guide will show you how to use Docker Compose to set up and run a Rails/PostgreSQL app. Before starting, you’ll need to have Compose installed.

Define the project

Start by setting up the four files you’ll need to build the app. First, since your app is going to run inside a Docker container containing all of its dependencies, you’ll need to define exactly what needs to be included in the container. This is done using a file called Dockerfile. To begin with, the Dockerfile consists of:

FROM ruby:2.3.3
RUN apt-get update -qq && apt-get install -y build-essential libpq-dev nodejs
RUN mkdir /myapp
WORKDIR /myapp
ADD Gemfile /myapp/Gemfile
ADD Gemfile.lock /myapp/Gemfile.lock
RUN bundle install
ADD . /myapp

That’ll put your application code inside an image that will build a container with Ruby, Bundler and all your dependencies inside it. For more information on how to write Dockerfiles, see the Docker user guide and the Dockerfile reference.

Next, create a bootstrap Gemfile which just loads Rails. It’ll be overwritten in a moment by rails new.

source 'https://rubygems.org' gem 'rails', ''

You’ll need an empty Gemfile.lock in order to build our Dockerfile.

touch Gemfile.lock

Finally, docker-compose.yml is where the magic happens. This file describes the services that comprise your app (a database and a web app), how to get each one’s Docker image (the database just runs on a pre-made PostgreSQL image, and the web app is built from the current directory), and the configuration needed to link them together and expose the web app’s port.

version: '3'
    image: postgres
    build: .
    command: bundle exec rails s -p 3000 -b ''
      - .:/myapp
      - "3000:3000"
      - db

Tip: You can use either a .yml or .yaml extension for this file.

Build the project

With those four files in place, you can now generate the Rails skeleton app using docker-compose run:

docker-compose run web rails new . --force --database=postgresql

First, Compose will build the image for the web service using the Dockerfile. Then it will run rails new inside a new container, using that image. Once it’s done, you should have generated a fresh app:

$ ls -l
total 64
-rw-r--r--   1 vmb  staff   223 May 19 11:05 Dockerfile
-rw-r--r--   1 vmb  staff  1738 May 19 11:06 Gemfile
-rw-r--r--   1 vmb  staff  4306 May 19 11:07 Gemfile.lock
-rw-r--r--   1 vmb  staff   374 May 19 11:06 README.md
-rw-r--r--   1 vmb  staff   227 May 19 11:06 Rakefile
drwxr-xr-x  10 vmb  staff   340 May 19 11:06 app
drwxr-xr-x   8 vmb  staff   272 May 19 11:07 bin
drwxr-xr-x  14 vmb  staff   476 May 19 11:06 config
-rw-r--r--   1 vmb  staff   130 May 19 11:06 config.ru
drwxr-xr-x   3 vmb  staff   102 May 19 11:06 db
-rw-r--r--   1 vmb  staff   212 May 19 11:06 docker-compose.yml
drwxr-xr-x   5 vmb  staff   170 May 16 15:05 getstart
drwxr-xr-x   4 vmb  staff   136 May 19 11:06 lib
drwxr-xr-x   3 vmb  staff   102 May 19 11:06 log
drwxr-xr-x   9 vmb  staff   306 May 19 11:06 public
drwxr-xr-x  20 vmb  staff   680 May 19 11:04 rails
drwxr-xr-x   2 vmb  staff    68 May 19 11:05 rails-new
drwxr-xr-x   9 vmb  staff   306 May 19 11:06 test
drwxr-xr-x   4 vmb  staff   136 May 19 11:06 tmp
drwxr-xr-x   3 vmb  staff   102 May 19 11:06 vendor

If you are running Docker on Linux, the files rails new created are owned by root. This happens because the container runs as the root user. If this is the case, change the ownership of the new files.

  sudo chown -R $USER:$USER .

If you are running Docker on Mac or Windows, you should already have ownership of all files, including those generated by rails new. List the files just to verify this.

If you edit Gemfile at this point or later, you will need to build the image again. (This, and changes to the Dockerfile itself, should be the only times you’ll need to rebuild.)

docker-compose build

Connect the database

The app is now bootable, but you’re not quite there yet. By default, Rails expects a database to be running on localhost - so you need to point it at the db container instead. You also need to change the database and username to align with the defaults set by the postgres image.

Replace the contents of config/database.yml with the following:

development: &default
  adapter: postgresql
  encoding: unicode
  database: myapp_development
  pool: 5
  username: postgres
  host: db

  <<: *default
  database: myapp_test

You can now boot the app with:

docker-compose up

If all’s well, you should see some PostgreSQL output, and then—after a few seconds—the familiar refrain:

web_1  | => Booting Puma
web_1  | => Rails application starting in development on
web_1  | => Run `rails server -h` for more startup options
web_1  | Puma starting in single mode...
web_1  | * Version 3.7.1 (ruby 2.3.3-p222), codename: Snowy Sagebrush
web_1  | * Min threads: 5, max threads: 5
web_1  | * Environment: development
web_1  | * Listening on tcp://

Finally, you need to create the database. In another terminal, run:

docker-compose run web rake db:create

Here is an example of the output from that command:

vmb at snapair in ~/sandbox/rails
$ docker-compose run web rake db:create
Starting rails_db_1 ... done
Created database 'myapp_development'
Created database 'myapp_test'

That’s it. Your app should now be running on port 3000 on your Docker daemon. On Docker for Mac and Docker for Windows, go to http://localhost:3000 on a web browser to see the Rails Welcome. If you are using Docker Machine, then docker-machine ip MACHINE_VM returns the Docker host IP address, to which you can append the port (<Docker-Host-IP>:3000).

Rails example

Stop the application

To stop the application, run docker-compose down in your project directory. You can use the same terminal window in which you started the database, or another one where you have access to a command prompt. This is a clean way to stop the application.

vmb at snapair in ~/sandbox/rails
$ docker-compose down
Stopping rails_web_1 ... done
Stopping rails_db_1 ... done
Removing rails_web_run_1 ... done
Removing rails_web_1 ... done
Removing rails_db_1 ... done
Removing network rails_default

You can also stop the application with Ctrl-C in the same shell in which you executed the docker-compose up. If you stop the app this way, and attempt to restart it, you might get the following error:

web_1 | A server is already
running. Check /myapp/tmp/pids/server.pid.

To resolve this, delete the file tmp/pids/server.pid, and then re-start the application with docker-compose up.

Restart the application

To restart the application:

  1. Run docker-compose up in the project directory.
  2. Run this command in another terminal to restart the database: docker-compose run web rake db:create

Rebuild the application

If you make changes to the Gemfile or the Compose file to try out some different configurations, you will need to rebuild. Some changes will require only docker-compose up --build, but a full rebuild requires a re-run of docker-compose run web bundle install to sync changes in the Gemfile.lock to the host, followed by docker-compose up --build.

Here is an example of the first case, where a full rebuild is not necessary. Suppose you simply want to change the exposed port on the local host from 3000 in our first example to 3001. Make the change to the Compose file to expose port 3000 on the container through a new port, 3001, on the host, and save the changes:

ports: - "3001:3000"

Now, rebuild and restart the app with docker-compose up --build, then restart the database: docker-compose run web rake db:create.

Inside the container, your app is running on the same port as before 3000, but the Rails Welcome is now available on http://localhost:3001 on your local host.

More Compose documentation

documentation, docs, docker, compose, orchestration, containers