- Set up your local environment for deploying with Heroku
- Deploy a basic Rails application to Heroku
In this lesson, we'll be deploying a basic, standalone Rails API application to Heroku. We'll give instructions to generate the application from scratch and talk through the steps to get the code running on a Heroku server.
In coming lessons, we'll learn how to add more complexity to the application with a React frontend. Since the setup for a Rails-React application is a bit trickier, it'll be beneficial to see the setup for Rails alone first. Let's get started!
To make sure you're able to deploy your application, you'll need to do the following:
You can sign up at for a free account at https://signup.heroku.com/devcenter.
Download the Heroku CLI. This will let you run commands from your terminal to deploy and interact with your application on Heroku.
For OSX users, you can use Homebrew to install the CLI:
$ brew tap heroku/brew && brew install heroku
For WSL users, run this command in the Ubuntu terminal:
$ curl https://cli-assets.heroku.com/install.sh | sh
If you run into issues installing, check out the Heroku CLI downloads page for more options.
After downloading, log in to Heroku via the CLI in the terminal:
$ heroku login
This will open a browser window to log you into your Heroku account. After
logging in, close the browser window and return to the terminal. You can run
heroku whoami
in the terminal to verify that you have logged in successfully.
Verify which version of Ruby you're running by entering this in the terminal:
$ ruby -v
Make sure that the Ruby version you're running is listed in the supported runtimes by Heroku. At the time of writing, supported versions are 2.6.8, 2.7.4, or 3.0.2. Our recommendation is 2.7.4, but make sure to check the site for the latest supported versions.
If it's not, you can use rvm
to install a newer version of Ruby:
$ rvm install 2.7.4 --default
You should also install the latest versions of bundler
and rails
:
$ gem install bundler
$ gem install rails
Heroku requires that you use PostgreSQL for your database instead of SQLite. PostgreSQL (or just Postgres for short) is an advanced database management system with more features than SQLite. If you don't already have it installed, you'll need to set it up.
To install Postgres for WSL, run the following commands from your Ubuntu terminal:
$ sudo apt update
$ sudo apt install postgresql postgresql-contrib libpq-dev
Then confirm that Postgres was installed successfully:
$ psql --version
Run this command to start the Postgres service:
$ sudo service postgresql start
Finally, you'll also need to create a database user so that you are able to connect to the database from Rails. First, check what your operating system username is:
$ whoami
If your username is "ian", for example, you'd need to create a Postgres user with that same name. To do so, run this command to open the Postgres CLI:
$ sudo -u postgres -i
From the Postgres CLI, run this command (replacing "ian" with your username):
$ createuser -sr ian
Then enter control + d
or type logout
to exit.
This guide has more info on setting up Postgres on WSL if you get stuck.
To install Postgres for OSX, you can use Homebrew:
$ brew install postgresql
Once Postgres has been installed, run this command to start the Postgres service:
$ brew services start postgresql
Phew! With that out of the way, let's get started on building our Rails application and deploying it to Heroku.
We'll be following the steps in the Heroku Rails Deploying Guide, so if you get stuck and are looking for more assistance, check that guide first.
The first thing we'll need to do is create our new Rails application. Make sure you're in a non-lab directory, then run:
$ rails new bird-app --api --minimal --database=postgresql
This will set up our app to run in API mode, with the minimum dependencies needed, and with Postgresql as the database.
Next, we'll need to configure our Gemfile.lock
file to support the same OS as
Heroku, which runs Ubuntu. This way, regardless of what OS you're using in
development, bundler
will be able to install the same gems on Heroku using any
Ubuntu-specific gem dependencies.
cd
into the app, and run this command:
$ bundle lock --add-platform x86_64-linux --add-platform ruby
This will add additional platforms to your Gemfile.lock
file that will allow
the necessary dependencies to be installed after you deploy your app.
Next, let's set up up a migration, model, route, and controller so that we have some data to display in our application:
$ rails g resource Bird name species
Add this data to the db/seeds.rb
file:
Bird.create!(name: 'Black-Capped Chickadee', species: 'Poecile Atricapillus')
Bird.create!(name: 'Grackle', species: 'Quiscalus Quiscula')
Bird.create!(name: 'Common Starling', species: 'Sturnus Vulgaris')
Bird.create!(name: 'Mourning Dove', species: 'Zenaida Macroura')
Then run this command to generate the database and run the migrations and seed file:
$ rails db:create db:migrate db:seed
rails db:create
creates a new Postgresql database to be associated with your application based on the configuration in theconfig/database.yml
file. Unlike with SQLite, the actual database file isn't created in thedb
folder; it lives elsewhere in your file system, depending on your Postgresql configuration. If you have problems with this step, see the Troubleshooting section below.
Finally, edit the app/birds_controller.rb
file and add an index
action:
# GET /birds
def index
birds = Bird.all
render json: birds
end
To make sure the app works locally before deploying, run rails s
and visit
http://localhost:3000/birds.
Now that we've got some working code, it's time to get that code to run on a Heroku server! The process of uploading our code to Heroku is managed by Git. This makes it easy to deploy new versions using a tool most developers, including yourself, are already familiar with.
Make a commit to save your changes:
$ git add .
$ git commit -m 'Initial commit'
Next, you'll need to create an application on Heroku:
$ heroku create
This command will generate a new application in your Heroku account, and configure a new remote repository where you can push up your code. You can confirm the remote repository was created successfully by running:
$ git config --list --local | grep heroku
remote.heroku.url=https://git.heroku.com/aqueous-sierra-44713.git
remote.heroku.fetch=+refs/heads/*:refs/remotes/heroku/*
Now, deploying your code is as simple as using git push
to upload the changes
from your repository to Heroku:
$ git push heroku main
Note: depending on your Git configuration, your default branch might be named
master
ormain
. You can verify which by runninggit branch --show-current
. If it'smaster
, you'll need to rungit push heroku master
instead.
You've successfully pushed up your code!
After pushing up your code, you'll notice a flurry of activity in the terminal. This indicates that Heroku is in the process of building your application, by:
- Setting up a Ruby environment to run your code in
- Installing the gems for your project with
bundle install
- Running
rails server
to start up your server
If the build process succeeds, your app is live and online!
Before visiting the site, let's also set up the database. Remember, the database is a separate application from your Rails application. Thankfully, we can get it set up easily by running a few Rake commands on the server.
To migrate and seed the database on the server, run:
$ heroku run rails db:migrate db:seed
When you prefix any command with heroku run
, it will run that command on the
server where your application was deployed. This command is very useful for
troubleshooting: you can even run heroku run rails c
to open a Rails console
on the server!
You can now visit the site in the browser by running heroku open
. Note that,
because there is no root path ('/'
) defined in our routes, you will see a
Page Not Found error when the app opens.
Navigate to the /birds
endpoint and verify that you are able to see an array
of JSON data for all the birds in the database. If you aren't able to, check out
the troubleshooting section below, or the
troubleshooting guide on Heroku.
Since Heroku integrates the deploying process with Git, it's straightforward
to add new features to your code and deploy them. Let's start by adding a new
controller action in the BirdsController
:
def show
bird = Bird.find(params[:id])
render json: bird
rescue ActiveRecord::RecordNotFound
render json: "Bird not found", status: :not_found
end
Test your code locally by running rails s
and visiting
http://localhost:3000/birds/1.
After adding this code, make a commit:
$ git add app/controllers/birds_controller.rb
$ git commit -m 'Added show action'
Then, to deploy the changes, push the new code up to Heroku:
$ git push heroku main
After pushing new code, Heroku will run through the build process again and deploy your changes. You don't have to run your migrations again since the database already exists on the server. You would have to run the migrations if you created a new migration file.
If you ran into any errors along the way, here are some things you can try to troubleshoot:
-
If you're on a Mac and got a server connection error when you tried to run
rails db:create
, one option for solving this problem for Mac users is to install the Postgres app. To do this, first uninstallpostgresql
by runningbrew remove postgresql
. Next, download the app from the Postgres downloads page and install it. Launch the app and click "Initialize" to create a new server. You should now be able to runrails db:create
. -
If you're using WSL and got the following error running
rails db:create
:PG::ConnectionBad: FATAL: role "yourusername" does not exist
The issue is that you did not create a role in Postgres for the default user account. Check this video for one possible fix.
-
If your app failed to deploy at the build stage, make sure your local environment is set up correctly by following the steps at the beginning of this lesson. Check that you have the latest versions of Ruby and Bundler, and ensure that Postgresql was installed successfully.
-
If you deployed successfully, but you ran into issues when you visited the site, make sure you migrated and seeded the database. Also, make sure that your application works locally and try to debug any issues on your local machine before re-deploying. You can also check the logs on the server by running
heroku logs
.
For additional support, check out these guides on Heroku:
Congrats on deploying your first Rails app to the world wide web! Understanding the deployment process and what it takes to run your application on another computer is an important step toward becoming a full-stack developer. Like anything new, this process can be daunting the first time you try it, but with practice and exposure, you'll build confidence over time.
In the next lesson, we'll work on deploying a more complex application with a Rails API backend and a React frontend, and talk through some of the challenges of running these two applications together.
Before you move on, make sure you can answer the following questions:
- When creating a new Rails app from the terminal, what additional flag do you need to use to be able to deploy it on Heroku?
- What familiar process is used for deploying code to Heroku? How does the process differ when you're deploying to Heroku vs. developing code locally?