Ruby on Rails - Deployment

---

---

So far, we have learned about various features of the Rails framework by building the applications on the locally running Puma server. In this chapter, we will learn how to deploy a Rails application on a publicly accessible server.

Deploy with Rails Kamal

Rails comes with a deployment tool called Kamal that we can use to deploy our application directly to a server. Kamal uses Docker containers to run your application and deploy with zero downtime. It is a simple, SSH-based deployment tool for Dockerized applications across any host or cloud provider. It is a lightweight, straightforward alternative to heavier tools like Kubernetes, or cloud-specific services like Heroku or AWS ECS.

To deploy with Kamal, we need −

• A server running Ubuntu LTS with 1GB RAM or more.
• A Docker Hub account and access token. Docker Hub stores the image of the application so it can be downloaded and run on the server.

On Docker Hub, create a Repository for your application image. Use "library" as the name for the repository.

When you create a new Rails application with Rails new command, the dockerfile gem is automatically added.

# Deploy this application anywhere as a Docker container [https://kamal-deploy.org]
gem "kamal", require: false

Note that Docker must be installed on your local machine and target servers, and have SSH access to your remote VPS.

Kamal Configuration File

Rails creates the config/deploy.yml file. This is the Kamal configuration file.

It defines the following −

• Service name
• Docker image name
• List of remote servers
• Registry and environment settings

For example, your deploy.yml might look like −

# Name of your application. Used to uniquely configure containers.
service: library

# Name of the container image.
image: your-user/library

# Deploy to these servers.
	servers:
		web:
			- 192.168.0.1

	proxy:
		ssl: true
		host: app.example.com

	# Credentials for your image host.
	registry:
		username: your-user
		password:
			- KAMAL_REGISTRY_PASSWORD

	env:
		secret:
			- RAILS_MASTER_KEY
		clear:
			# Run the Solid Queue Supervisor inside the web server's Puma process to do jobs.
			# When you start using multiple servers, you should split out job processing to a dedicated machine.
			SOLID_QUEUE_IN_PUMA: true

	aliases:
		console: app exec --interactive --reuse "bin/rails console"
		shell: app exec --interactive --reuse "bash"
		logs: app logs -f
		dbc: app exec --interactive --reuse "bin/rails dbconsole"

	volumes:
		- "library_storage:/rails/storage"


	asset_path: /rails/public/assets

	# Configure the image builder.
	builder:
		arch: amd64

Note that you should replace 192.168.0.1 with your server's IP address and your-user with your Docker Hub username.

DockerFile

You will also find DockerFile in the project structure, ready to containerize your Rails app. It includes steps to install system dependencies, bundle gems, precompile assets, and launch the app. You can customize it to add JS tools (e.g., Node, esbuild, Tailwind).

The DockerFile includes −

• Ruby image base (e.g., ruby:3.2)
• System package installs (nodejs, postgresql-client, etc.)
• bundle install
• Asset precompilation
• Puma server boot command

Here’s a sample Dockerfile −

FROM ruby:3.2

# Install dependencies
RUN apt-get update -qq && apt-get install -y nodejs postgresql-client

# Set working directory
WORKDIR /app

# Install gems
COPY Gemfile* ./
RUN bundle install

# Copy the rest of the app
COPY . .

# Precompile assets and prepare production
RUN bundle exec rake assets:precompile

# Start server
CMD ["bash", "-c", "bundle exec rails db:migrate && bundle exec puma -C config/puma.rb"]

A file named as .dockerignore is also created. It works like .gitignore, but for Docker builds. Its purpose is to prevent unnecessary files (like log/, tmp/, node_modules/, .git/) from being added to the Docker image.

Kamal Commands

Listed below are the important commands in Kamal −

• kamal build − Builds the Docker image
• kamal push − Pushes the image to the container registry
• kamal deploy − Deploys the image on the server
• kamal env push − Syncs secret environment variables
• kamal rollback − Rolls back to the previous deployment
• kamal ssh app − SSH into the running container

To set up your server and deploy your application for the first time, run the following command −

bin/kamal deploy