Introduction
At Krystal, we’re passionate about Ruby, and the latest buzz in the Rails community has us excited. With the release of Rails 8 and Kamal 2 for deployment, Rails is doubling down on the “one-developer framework,” reducing complexity and making it easier to build applications without relying on platform-as-a-service providers.
In this post we’ll show you how you can set up a Rails 8 application using Kamal 2.2 and deploy it on a Virtual Machine with our cloud hosting platform, Katapult. When you sign up, you’ll get £100 free credit and you can launch a Virtual Machine for just £10/month.
Create a Ruby on Rails 8 Application
Start by creating your app:
gem install rails
rails new katapult_rails_demo
cd katapult_rails_demo
bin/setup
Visit http://localhost:3000 to check it’s working.
Rails 8 makes it easy by automatically configuring for out-of-the-box deployment. The deployment configuration is declared in config/deploy.yml. For more details, you can refer to the Kamal documentation.
TIP: If you want to deploy an older Rails version, it’s a good idea to set up a Rails 8 demo app first. Pay attention to files like the Dockerfile, bin/docker-entrypoint, config/database.yml, config/environments/production.rb and new Rails settings such as assume_ssl.
Docker
Rails 8 comes with a ready-to-go Production Dockerfile, and Kamal handles pushing it to the container registry of your choice (default: Docker Hub). If necessary, create a Docker Hub Account, then generate a personal access token with “read, write, and delete” permissions.
Kamal securely retrieves its secrets from the .kamal/secrets file which Rails has pre-configured to read the KAMAL_REGISTRY_PASSWORD environment variable.
Additionally, Kamal also enables the dotenv gem.
Create a .env file at the root of your app directory and add:
KAMAL_REGISTRY_PASSWORD=youraccesskey
NOTE: The .env file is already configured by Rails to be in the .gitignore file, this won’t be checked into the Git repo for security reasons. (I like to double check .gitignore just to be sure)
Update config/deploy.yml with your Docker Hub username and image:
image: your_docker_hub_username/katapult_rails_demo
# ...
registry:
username: your_docker_hub_username
SSH Keys
Sign up for a Katapult account (don’t forget your £100 credit!). Add your SSH key via Krystal Identity, and it will automatically sync with your VM.
NOTE: Krystal Identity is our single sign on platform for managing all your Krystal services from a single account.
Launch your Virtual Machine
Choose from our data centers (UK, US, or Netherlands), configure your VM settings (or leave defaults), and once your VM is ready, update config/deploy.yml with the IP address of your new Katapult VM:
servers:
web:
- 192.168.0.1
Set the Host for the Kamal Proxy
If you have your own domain name, you can configure it and use it (Katapult offers DNS management too). For testing purposes, you can use the unique name assigned to your VM. Update the Kamal proxy config like this:
proxy:
ssl: true
host: rails-is-great.yourorg.katapult.cloud
Commit your changes
Each time you deploy, ensure there are no unstaged changes in the Git repository. You don’t need to push the repo anywhere–just commit them to Git via:
git commit -m "initial commit"
Kamal setup
Run the setup command:
dotenv kamal setup
The first run may take a while, but future deployments will be faster.
Prefix the command with dotenv to ensure the environment variables from the .env file are loaded. Alternatively, you can modify config/deploy.yml to explicitly require dotenv for loading these variables automatically.
It's alive
Now you should be able to view your application at the host you declared earlier. The SSL certificate will have been automatically provisioned via Let’s Encrypt.
If your app doesn’t even have any controllers yet, you can always visit /up to see the nice green health-check page. For future deploys, commit your changes to Git and run:
dotenv kamal deploy
Refer to the Kamal documentation to learn about all the other commands you can run.
And that’s it, your Rails app is running on a Katapult Virtual Machine, deployed using Kamal.
Share this article
About the author
Paul S
Paul is a software engineer for Krystal, he works on Krystal's cloud hosting platform Katapult. Outside of work he enjoys music, football, gardening and spending time with his kids.