Heads up! This guide was written for Rails 5.3. While it should also hold true for the latest version, certain things might break (e.g. rbenv installation now comes with ruby-build automatically, at least on macOS). I will publish the guide for Rails 6.x only after I deploy one myself, the timelines of which are unknown at the moment. {: .notice—danger}
There are tons of Ruby on Rails deployment guide. So why this one? Why yet another guide on how to deploy a Rails application?
Fact be said, I have been coding in Rails for well above 1.5 years now (as of this writing). I started with a Rails 4 application at work where the app ran on multiple servers, behind a load balancer. The deployment was done using a bash script. The script was kind of crude and many-a-times I myself wished to improve it and thought there has to be other way to get things done, until a few days back.
I recently wrote a Rails app myself using Rails version 5.2. Though I started writing the app as a normal Rails appliation (not an --api one) but quickly changed it to an API-only project because of how the development was going. In addition I also wanted to know how to create a Vue based SPA so I went ahead with converting the app to a API based app.
Then came the deployment part. I thought I will improvise and use tools that make sense. So I started looking for deployment tools and it was then that I realised certain things.
Complications
- There are a number of combinations for almost every tool you would want in a production stack.
- There are no standard choices on any of them and Rails makes no recommendation in their official guide either.
- There are differences between development and deployment and if you are new, they’d confuse you pretty easily.
- There are two types of guides available (from my observation) - one which assume you already are very well versed with Rails and you just need an introduction to a deployment tool and the other type - where the writer assumes you are an idiot who needs to be taken step by step for every single thing (including creation and development of a Rails app) without telling in detail what’s happening.
- All guides are centered around tooling - they make choices and just follow them - some of them don’t even explain why they are doing what they are doing.
It was then that I realised that Rails Deployment is not easy - there are too many tools and there is too less information on what to do, what each step means, why should we make any selection on tooling and what if the reader’s tooling is different.
Once I had the clarity of what I wanted, I appreciated the crude looking deployment script that we were using in our company and I decided to shed some light on Rails Deployment and how to go about it.
About this guide
This guide has assumptions of its own but we will explain why we are doing what we are doing. We will talk about what each tool does and why we need them. If you want to change certain tools, you should be able to do that.
I am going to assume you already know how to develop a Rails app, so I am not going to talk about it. You should know:
- how to create a Ruby on Rails (RoR) project
- how to create routes, controllers and views and how to render them
- how to create API endpoints
- how to create models
- how to write your own migrations for altering database schema
- how to install Gems using Gemfile etc.
If you need help on those, you should probably skip this guide and first learn the above mentioned things - they are the basics of building a Rails app.
NOTE: Throughout the guide, you will find terminal commands to run. When you do, remember that some of them will include lines with the prompt (the $ sign). Anything till the prompt is shown by the system and the command is written after the prompt; but you already understand that, don’t you?
{: .notice—warning}
NOTE 2: If you get stuck somewhere, let me know by commenting on the article where you get stuck. The comment section is below the article. {: .notice—info}
Why not just use Capistrano (or something else)?
The steps we will be following in this guide closely resembles that of capistrano. Even Mina does nearly the same thing.
Why then did I take the pain of write this guide?
Because I love keeping things under control. I have seen failed deployments and that’s when you need to know how to go through the logs and figure what went southwards. While most deployment tools do logging of their actions as part of the deployment process, it is another thing to go through them to figure out what the logs mean. With a script, you:
- have to ability to customize messages that are thrown at you
- write checks you want
- automate creation of directories
- can type github username and password (if you so desire) instead of setting up a deployment key
- don’t need to go through a DSL.
It goes without saying that if you already know how to use the deployment tool of your choice (e.g. Capistrano) then maybe this is not a guide you would love to use or read. However, if you want more interactiveness during deployment, or you want more control over the process, and maybe more insight and want to know why the famous tools do what they do, then there is a good chance you will love reading this guide.
IMPORTANT NOTE on RoR version
This guide is written with Rails version 5.2 in mind but should mostly work with any other version from 4.1 and above till 5.2 as well.
Assuming you know the basics, let’s begin.