Wednesday, 2 November, 2022 UTC


Hi there Ruby developers! If you’ve been looking for an effective way to establish a Ruby on Rails Docker setup for your local development environment, then this post is for you. It’s a continuation of our previous article on how to install Ruby in a macOS for local development.
Ruby developers frequently need to account for a database when building a Ruby on Rails project, as well as other development environment prerequisites. However, ensuring all of these are installed on your host operating system — and use the exact required versions — might sometimes be a challenge.
Every time I was attempting to create a new project, I found myself wishing for a button that created a new, clean environment for it.  So, I decided to create a Docker-powered setup that can easily be started and stopped using Docker’s docker-compose.yml.

What is Docker Compose?

Docker Compose is an Infrastructure as Code (IaC) tool that allows you to configure and connect applications and services such as proxies, databases, and volume mounts in order to provision them in a reusable way. It’s installed as part of the Docker software bundle, and defined using YAML.
This Docker Compose setup for a local development environment can be used for different types of projects, and isn’t solely applied to  Ruby on Rails. It could also be used in side-projects or frontend client-side projects. The main reasons I prefer to use Docker environments instead of changing my own host operating system include:
  • easy to configure
  • easy to split logic from the environment
  • easy to use the same env for different projects
  • easy to share the environment without any sensitive code to anyone who needs help with it
  • host machine stays clean
A Ruby on Rails Docker setup
In order to setup a Ruby on Rails Docker environment for local development, you’ll need the following:
  • Unix like OS (I use a macOS, but you can use Ubuntu or any other Linux distro. Windows should also work)
  • Git 
  • make (3.81 or later)
  • Docker (19.03.12 or later)
  • docker-compose (1.26.0 or later)
  • Your preferred text editor (Visual Studio Code in my case)
Once you have those, you’re ready to get started. For those who don’t want to read – here is the open source repository with all of the required instructions and the full source code to all of the snippets that we’ll review. B since you’re here already, simply follow this article for a step-by-step guide.
To start off I’ll create a Ruby on Rails project named foo_bar_project for the sake of simplicity. 
1) Get the Docker Compose environment configuration and remove the git repository. If you want to keep everything tracked through a git source-code repository, you can create your own later.
git clone [email protected]:mtereschenko/simple_ror_environment.git && cd simple_ror_environment && rm -rf .git
Next steps should be executed in the ./environment directory, so let’s make sure you are running commands inside it:
cd ./environment
2) Now, you need to assign a project name to this environment setup. By default, it’s test_project. In our code walkthrough here, we need to update it to match foo_bar_project as we’ve previously described. To do so, make the changes in the  ./environment/.env.example file to reflect it in the PROJECT_NAME variable. It’s important to use lower case Snake Case as values to variables:
3) Next you are ready to create your project by running the following command:
make init
As you can see, you now have a new folder called application with Ruby On Rails code inside.
4) Now you need to build your local development environment with Docker Compose. This step is obligatory after any changes in the Dockerfile or Gemfile of your application.
make build
5) This allows you now to spin up the Ruby local development environment as follows:
make start
Notice that this isn’t yet starting a Ruby on Rails application. To do that, we need to open a shell to the Docker environment and instruct it to start the rails process. We’ll do that as follows:
make shell
rails s -p 3000 –binding=
Finally, if you open your browser and navigate to this url, http://foo_bar_project.localhost/, you should see the Ruby on Rails project that we’ve just built.
So, what’s available for us now?
  • We have a project with an environment directory that contains all we need to run our project, and an application directory which contains our application code. This directory is mapped into the Docker container, so you have full access from the Ruby Docker image.
  • We have quick access to the Ruby shell, so we do not need to have a Ruby environment installed locally, such as Rails, Rake, Bundler, or any other Ruby toolchain.
  • Commands can be executed after the make shell command.
  • This Docker Compose setup of the project has two preconfigured stages, so if you ever need to deploy your Ruby application somewhere, you can create your own stage. It’s as simple as that!
If you’re keen on how the above Docker environment for Ruby on Rails works, we’re going to break it down into the Ruby Docker image, the Makefile, and the Docker Compose definition that makes all of it tick together.
A Ruby Docker image
First off, the Ruby Docker image is an essential part, and building it correctly is also important to ensure that we have an effective re-use of Docker image layers cache, and other concerns relating to a local development environment.
Following is the Dockerfile for the Ruby Docker image:
FROM ruby:2.7.6-alpine3.16 as base_image
RUN apk add --no-cache git \
    build-base \
    libpq-dev \

FROM base_image as development
COPY ./artifacts/rails/Gemfile /tmp/Gemfile
COPY ./artifacts/rails/Gemfile.lock /tmp/Gemfile.lock
COPY ./containers/ruby/runners/ /rdebug_ide/
RUN cd /tmp && \
  gem install ruby-debug-ide && \
  gem install debase && \
  bundle install && \
  chmod +x /rdebug_ide/ && \
  apk add --no-cache git \
  nodejs \

ENTRYPOINT ["tail", "-f", "/dev/null"]

FROM base_image as init
COPY ./containers/ruby/initializers/ /tmp/
COPY ./containers/ruby/initializers/database.yml /tmp/database.yml
COPY ./containers/ruby/initializers/.gitignore /tmp/.gitignore
COPY ./containers/ruby/initializers/development.rb /tmp/development.rb
RUN chmod +x /tmp/


ENTRYPOINT ["/tmp/"]
As you can see, it makes some assumptions on peripheral configuration that is needed to have a functional Ruby on Rails application environment, such as:
  • database.yml file that is seeded for the Ruby on Rails database connection details
  • development.rb for Ruby on Rails runtime configuration for the development environment
It does so using the script in the ./environment/containers/ruby/initializers directory:

cd /app

gem install rails

rails new . -d=postgresql --skip-git

yes | cp -rf /tmp/database.yml /app/config/database.yml
yes | cp -rf /tmp/development.rb /app/config/environments/development.rb
cp /tmp/.gitignore /app/.gitignore
This Dockerfile also makes use of Multistage Docker, so that specific parts can be effectively reused throughout different environments if you wish to use the same setup for different workflows (testing, staging, and so on).
A Rails Docker Compose
The Docker Compose file in `./environment/docker-compose.development.yml` helps glue all the services together for a functional Ruby on Rails application on Docker:
  • An nginx HTTP server
  • A Ruby application
  • A PostgreSQL database server
The following is the Rails Docker Compose file in use by this setup:
version: '3.7'
    image: "${PROJECT_NAME}/nginx:development"
    container_name: ${PROJECT_NAME}-nginx
      context: ./
      dockerfile: ./containers/nginx/Dockerfile
      - ruby
    tty: true
      - 80:80
      - ./`artifacts`/nginx/:/`var`/log/nginx:cached
    image: "${PROJECT_NAME}/ruby:development"
    container_name: ${PROJECT_NAME}-ruby
      - postgres
      context: ./
      dockerfile: ./containers/ruby/Dockerfile
      target: development
      - 13030:13030
      - ${APP_PATH}:/app:cached
      DB_NAME: ${DB_NAME}
      DB_USER: ${DB_USER}
      DB_PORT: ${DB_PORT}
    image: "${PROJECT_NAME}/postgres:development"
    container_name: ${PROJECT_NAME}-postgres
      context: ./
      dockerfile: ./containers/postgres/Dockerfile
      - ${DB_PORT}:5432
      - postgres_volume:/var/lib/postgresql/data

Makefile for Docker
Finally, in order to create an accessible interface for developers to easily interact with this local development environment for Ruby, a Makefile is used:
.PHONY: help
# Make stuff

-include .env



ARTIFACTS_DIRECTORY := "./artifacts"

CURRENT_PATH :=${abspath .}

SHELL_CONTAINER_NAME := $(if $(c),$(c),ruby)
BUILD_TARGET := $(if $(t),$(t),development)

help: ## Help.
	@grep -E '^[a-zA-Z-]+:.*?## .*$$' Makefile | awk 'BEGIN {FS = ":.*?## "}; {printf "[32m%-27s[0m %s\n", $$1, $$2}'

init: ## Project installation.
	@rm -f ./.env
	@cp .env.example .env
	@make init_app_directory
	@make create_postgress_volume
	@docker-compose -f docker-compose.init.yml build
	@docker-compose -f docker-compose.init.yml up

build: ## Build images.
	@make create_project_artifacts
	@cp ${APP_PATH}/Gemfile "${ARTIFACTS_DIRECTORY}/rails/Gemfile"
	@cp ${APP_PATH}/Gemfile.lock "${ARTIFACTS_DIRECTORY}/rails/Gemfile.lock"
	@docker-compose -f docker-compose.$(BUILD_TARGET).yml build

shell: ## Internal image bash command line.
	@if [[ -z `docker ps | grep ${SHELL_CONTAINER_NAME}` ]]; then \
		echo "${SHELL_CONTAINER_NAME} is NOT running (make start)."; \
	else \
		docker-compose -f docker-compose.$(BUILD_TARGET).yml exec $(SHELL_CONTAINER_NAME) /bin/ash; \
start: ## Start previously builded application images.
	@make create_project_artifacts
	@make start_postgres
	@make start_ruby
	@make start_nginx

run: ## Run ruby debugger session.
	@docker-compose -f docker-compose.$(BUILD_TARGET).yml exec ruby /bin/ash /rdebug_ide/

start_ruby: ## Start ruby image.
	@if [[ -z `docker ps | grep ruby` ]]; then \
		docker-compose -f docker-compose.$(BUILD_TARGET).yml up -d ruby; \
	else \
		echo "Ruby is running."; \

start_postgres: ## Start postgres image.
	@if [[ -z `docker ps | grep postgres` ]]; then \
		docker-compose -f docker-compose.$(BUILD_TARGET).yml up -d postgres; \
	else \
		echo "Postgres is running."; \

start_nginx: ## Start nginx image.
	@if [[ -z `docker ps | grep nginx` ]]; then \
		docker-compose -f docker-compose.$(BUILD_TARGET).yml up -d nginx; \
	else \
		echo "Nginx is running."; \

stop: ## Stop all images.
	@docker-compose -f docker-compose.$(BUILD_TARGET).yml stop

	mkdir -p ./artifacts/rails
	mkdir -p ./artifacts/db

	@mkdir -p ${APP_PATH}

	@sed -i '' -r  "s/postgres_volume:/${PROJECT_NAME}_db_volume:/g" docker-compose.development.yml
Running Ruby applications efficiently
Hopefully you’ve now earned a new skill of running Ruby applications, such as Ruby on Rails, on your local environment, via the use of Docker containers configuration. Another way of running local Ruby applications is through the use of Ruby virtual environments, which we covered previously in our post on how to install Ruby on macOS.
Now that you’ve got your Ruby development environment all worked out, you might also want to learn how to secure your Ruby applications. Check out the following articles for more information on Ruby security:
  • Scanning Ruby gems with Snyk
  • A definitive guide to Ruby gems dependency management
Secure your Ruby applications for free
Create a Snyk account today to find and fix vulnerabilities in your Ruby containers.
Sign up for free