awesome-compose/official-documentation-samples/rails

Quickstart: Compose and Rails

This Quickstart guide shows you how to use Docker Compose to set up and run a Rails/PostgreSQL app. Before starting, install Compose.

Define the project

Dockerfile

Start by setting up the files needed to build the app. The app will run inside a Docker container containing its dependencies. Defining dependencies is done using a file called Dockerfile. To begin with, the Dockerfile consists of:

# syntax=docker/dockerfile:1
FROM ruby:3.2.2

# Install postgres client
RUN apt-get update && apt-get install -y postgresql-client

WORKDIR /app
COPY Gemfile /app/Gemfile
COPY Gemfile.lock /app/Gemfile.lock
RUN bundle install

COPY . /app

# Only necessary for production
# RUN rails assets:precompile

# Add a script to be executed every time the container starts.
COPY entrypoint.sh /usr/bin/
RUN chmod +x /usr/bin/entrypoint.sh
ENTRYPOINT ["entrypoint.sh"]

EXPOSE 3000

# Configure the main process to run when running the image
CMD ["rails", "server", "-b", "0.0.0.0"]

That'll put your application code inside an image that builds 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.

Set up Rails

Next, open an editor and create a bootstrap Gemfile which just loads Rails. This will be overwritten in a moment by rails new.

source 'https://rubygems.org'
gem 'rails', '~>7'

Create an empty Gemfile.lock file to build our Dockerfile.

$ touch Gemfile.lock

Next, provide an entrypoint script to fix a Rails-specific issue that prevents the server from restarting when a certain server.pid file pre-exists. This script will be executed every time the container gets started. entrypoint.sh consists of:

#!/bin/bash
set -e

# Remove a potentially pre-existing server.pid for Rails.
rm -f /app/tmp/pids/server.pid

# Then exec the container's main process (what's set as CMD in the Dockerfile).
exec "$@"

Compose file

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.

volumes:
  db-data:
  gems:

services:
  db:
    image: postgres:15
    volumes:
      - db-data:/var/lib/postgresql/data
    env_file: .env

  web:
    build: .
    volumes:
      - .:/app:z
      - gems:/usr/local/bundle
    ports:
      - "3000:3000"
    depends_on:
      # - maildev # for email in dev, optional
      - db
    env_file: .env

    # lets you use the debugger
    # stdin_open: true
    # tty: true
  
  # Shows you emails sent by Rails at localhost:1080
  # maildev:
  #  image: maildev/maildev:2.1.0
  #  ports:
  #    - "1080:1080"

  test:
    build: .
    volumes:
      - .:/app
      - gems:/usr/local/bundle
    depends_on:
      - db
      # - chrome-server # For system tests, optional
    environment:
      RAILS_ENV: test
    env_file: .env

    # lets you use the debugger
    # stdin_open: true
    # tty: true

  # For system tests, optional
  # chrome-server:
  #   image: selenium/standalone-chrome:114.0

Tip

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

Dot env file

You can see in the docker-compose.yml file:

env_file: .env

We need to create that .env file, with the following content:

POSTGRES_PASSWORD=uniquesecretpassword
POSTGRES_USER=postgres

Feel free to make them unique.

Note for later: if you commit your code to git, make sure to add this .env file that has your db password to .gitignore. You can use this file to store other secrets.

Build the project

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

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

First, Compose builds the image for the web service using the Dockerfile. The --no-deps tells Compose not to start linked services. Then it runs rails new inside a new container, using that image. Once it's done, you should have generated a fresh app.

List the files.

$ ls -l

total 64
-rw-r--r--   1 vmb  staff   222 Jun  7 12:05 Dockerfile
-rw-r--r--   1 vmb  staff  1738 Jun  7 12:09 Gemfile
-rw-r--r--   1 vmb  staff  4297 Jun  7 12:09 Gemfile.lock
-rw-r--r--   1 vmb  staff   374 Jun  7 12:09 README.md
-rw-r--r--   1 vmb  staff   227 Jun  7 12:09 Rakefile
drwxr-xr-x  10 vmb  staff   340 Jun  7 12:09 app
drwxr-xr-x   8 vmb  staff   272 Jun  7 12:09 bin
drwxr-xr-x  14 vmb  staff   476 Jun  7 12:09 config
-rw-r--r--   1 vmb  staff   130 Jun  7 12:09 config.ru
drwxr-xr-x   3 vmb  staff   102 Jun  7 12:09 db
-rw-r--r--   1 vmb  staff   211 Jun  7 12:06 docker-compose.yml
-rw-r--r--   1 vmb  staff   184 Jun  7 12:08 entrypoint.sh
drwxr-xr-x   4 vmb  staff   136 Jun  7 12:09 lib
drwxr-xr-x   3 vmb  staff   102 Jun  7 12:09 log
-rw-r--r--   1 vmb  staff    63 Jun  7 12:09 package.json
drwxr-xr-x   9 vmb  staff   306 Jun  7 12:09 public
drwxr-xr-x   9 vmb  staff   306 Jun  7 12:09 test
drwxr-xr-x   4 vmb  staff   136 Jun  7 12:09 tmp
drwxr-xr-x   3 vmb  staff   102 Jun  7 12:09 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.

This process added a lof of gems to your gemfile. One of them can be removed, as we will sidestep it:

Remove:

gem "webdrivers"

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.

Adapt the contents of config/database.yml.

The lines you need to add are marked with a comment.

default: &default
  adapter: postgresql
  encoding: unicode
  # add what's below this
  host: db
  username: <%= ENV['POSTGRES_USER'] %>
  password: <%= ENV['POSTGRES_PASSWORD'] %>
  # and above this
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>

development:
  <<: *default
  database: app_development


test:
  <<: *default
  database: app_test

You can now boot the app with docker compose up web.

$ docker compose up web

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

$ docker compose run web rails db:prepare

View the Rails welcome page!

That's it. Your app should now be running on port 3000 on your Docker daemon.

On Docker Desktop for Mac and Docker Desktop for Windows, go to http://localhost:3000 on a web browser to see the Rails Welcome.

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.

$ 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

Restart the application

To restart the application run docker compose up web in the project directory.

Rebuild the application

If you make changes to the Gemfile or the Compose file to try out some different configurations, you need to rebuild. Some changes 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.

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.

Configure mail

The app includes a maildev server so you can view emails sent by your app. Uncomment the maildev service in docker-compose.yml if your app needs to send email.

Then add this to config/development.rb

config.action_mailer.delivery_method = :smtp
config.action_mailer.smtp_settings = {
  :address => 'maildev',
  :port => 1025,
  :openssl_verify_mode => 'none'
}

Now set up a mailer and view all emails sent by your app at http://localhost:1080

How to use rails in Docker Compose

At this point, your dev environement is set up. You can create your models and scaffold by piping rails to the correct container. Simply prefix "docker compose run web" to your command. For example, let's generate a scaffold.

docker compose run web rails generate scaffold Post title:string body:text

You can edit files locally and see the result in your browser. Just edit the routes files to point to Post#index and your new blogging platform is ready. As soon as you've migrated the database, that is:

docker compose run web rails db:migrate

If you want to see the routes:

docker compose run web rails routes

NB: you can pipe it to other commands.

docker compose run web rails routes | grep articles

And the rails console is waiting for you at

docker compose run web rails console

Install some gems you added to your Gemfile:

docker-compose run web bundle install

Drop in a terminal inside the rails container:

docker-compose run web bash

Run some tests

The test environment has some setup steps as well. Mostly related to system tests. In fact, your regular tests are already ready to run.

Once you migrate your test database of course:

docker compose run test rails db:migrate
docker compose run test rails test

Note how we're not using the "web" container, but from the "test" container.

Your system tests however, the ones that fire up an actual browser and simulate clicks and keyboard entries, these tests won't work yet, as we need to point Rails to the Chrome browser included in the app in the "chrome-server" service.

If you don't need system tests, ignore the next part.

Set up the browser for system tests

First, uncomment the chrome-server service in the docker-compose.yml

Point Capybara to the browser

Rails expects the browser to be local. We need to point it to the chrome-server.

Adapth the driver definition in test/application_system_test_case.rb

driven_by :selenium, using: :headless_chrome, screen_size: [1400, 1400], options: {
    browser: :remote,
    url: "http://chrome-server:4444/wd/hub"
  }

Point the browser to your app

In test/test_helper.rb, add:

Capybara.server_host = "0.0.0.0"
Capybara.app_host = "http://#{ENV.fetch("HOSTNAME")}:#{Capybara.server_port}"

It should be at the base of the file, outside of the TestCase class definition.

Now you can run your system tests:

docker compose run test rails test:system

More Compose documentation

• Docker Compose overview
• Install Docker Compose
• Getting Started with Docker Compose
• Docker Compose Command line reference
• Compose file reference