Debugging Rails in Docker

Photo by Nishant Kirar on Unsplash

With the rise of containerization, Docker has become a popular solution for isolating application environments. This is especially useful when developing and deploying Rails applications. Managing a Rails app and its databases in separate containers offers flexibility and scalability, but it can also introduce some challenges when it comes to debugging.

Starting from Rails 7.1, the Rails framework introduced built-in support for Docker. This allows developers to easily generate a Dockerfile as part of the app setup. This feature eliminates the need to manually create Docker configuration files, making it easier for developers to containerize their applications from the start.

To generate the Docker setup, you can use the command:

rails new myapp --docker

This automatically creates both a Dockerfile and a docker-compose.yml file, simplifying the process of setting up development and production environments using containers.

Now that Docker integration has been streamlined, let’s discuss the process of debugging Rails applications inside Docker.

Setting Up for Debugging

Once Docker is set up for your Rails app, I recommend using the Ruby gem pry-remote for debugging. This gem allows you to remotely interact with your app while it’s running in a container, making debugging much easier.

Here’s a simplified version of my docker-compose.yml configuration:

application:
  ports:
    - 30000:30000
  environment:
    - RUBY_DEBUG_ENABLE=0
    - RUBY_DEBUG_OPEN=true
    - RUBY_DEBUG_PORT=30000
    - RUBY_DEBUG_HOST=0.0.0.0
    - RUBY_DEBUG_SKIP_BP=true

These configurations are specifically for enabling remote debugging. For the sake of brevity, I’ve left out other settings like volumes, network, platform, and additional environment variables. These are often specific to individual Rails applications and usually don’t affect the debugging process.

In addition to the Docker setup, I modify my Procfile (or Procfile.dev, depending on the setup). In this file, I specify the command to start the Rails server:

web: RUBY_DEBUG_ENABLE=1 bundle exec puma -C config/puma.rb

The key is to set the environment variable RUBY_DEBUG_ENABLE=1 before starting your server. This enables the debug mode needed for pry-remote.

Running Your Rails App in Docker

Assuming your Rails application is already running inside a Docker container, open a terminal and run the following command to list all containers:

docker ps -a

This will display a list of all active containers, including the one running your Rails app. You should see something like this:

CONTAINER ID   IMAGE                COMMAND                  CREATED         STATUS         PORTS                                              NAMES
69d0dd296173   rails-app    "/entrypoint /bin/ba…"   14 minutes ago   Up 14 minutes   0.0.0.0:3000->3000/tcp, 0.0.0.0:30000->30000/tcp   rails-application-run-5241494c53

Take note of the NAMES column. This value identifies your Rails application container. For example, here it’s rails-application-run-5241494c53.

Debugging with Pry-Remote

To start debugging, open a new terminal session and run the following command to access the Rails application container:

docker exec -it rails-application-run-5241494c53 /bin/bash

This will give you a bash shell inside the container where your Rails app is running. Now, you can set breakpoints in your code using binding.remote_pry.

When the code hits a binding.remote_pry line, execution will pause, allowing you to inspect the state of your application.

In the second terminal session (the one shown above where you accessed the container), run:

pry-remote

This will open a Pry console at the point where your breakpoint is set. You can now interact with your application, inspect variables, and step through the code just like you would when debugging a Rails app outside of Docker.

Important Notes

In some setups, you may need to prefix certain commands with bundle exec. For example, to run pry-remote, you might need to run:

bundle exec pry-remote

If you modify your docker-compose.yml or Rails app files, don’t forget to restart the containers to apply the changes. You can use:

docker-compose down -v
docker-compose up

By following these steps, you can seamlessly debug your Rails app running inside a Docker container using pry-remote. This method ensures you can pause execution, inspect your app, and fix issues just like you would on a non-containerized setup.