Step through the process of deploying a Rails app to Heroku.
Switch branches/tags
Nothing to show
Clone or download

README.md

General Assembly Logo

Rails Deployment with Heroku

You've learned a lot about how to build a Rails application over the last few weeks. Now let's "go public" and share our apps with the world!

Prerequisites

Objectives

  • Create a repository on GitHub for your project.
  • Create a Heroku app from the command line.
  • Push the latest code to Heroku.
  • Migrate the production database.
  • Grab the link to your deployed API and paste it into the api_url.txt file.
  • Open a Pull Request to the GA repo so that we may check your API link.

Getting Set Up

Before you can begin deploying your applications to Heroku, there are some things you'll need to do first.

  1. Create a GitHub repository for your project, at Create a repo.
  2. Create a Heroku account, at Create a Heroku Account. You will be sent an activation email, so be sure to check your inbox so that you can activate your account.
  3. Install the Heroku Command Line Tools:
    • On macOS, run brew install heroku/brew/heroku.
    • On Ubuntu/WSL, run curl https://cli-assets.heroku.com/install.sh | sh.
  4. Login to Heroku by running heroku auth:login from the console and providing your Heroku credentials when asked. Once you log in, if you're prompted to add these credentials to your keychain, say yes. You will not be able to see your password.

Deploying to Heroku: Checklist

Now you're set up to use Heroku. To deploy a new application to Heroku:

  • Run heroku create in the command line in the root of your Rails API to create a new (blank) app on Heroku.
  • Push your latest code to Heroku (git push heroku master).
  • Update your Heroku database by telling Heroku to run your migration files (heroku run rails db:migrate). If you have any other rails tasks that need to run (e.g. rails db:seed), run those with heroku run as well.
  • Set your secrets: either by using the command line or by using the heroku app panel in your browser.
  • Check your work by restarting Heroku (heroku restart) and opening your heroku application.

Let's look at each of these steps in detail.

Create a New Heroku App

Go to the root of your repo and run heroku create. This will create an autogenerated name for your app, and add a new remote repository to your repo called heroku. View your remotes by typing git remote -v. You should see something like:

    heroku  git@heroku.com:agile-badlands-7658.git (fetch)
    heroku  git@heroku.com:agile-badlands-7658.git (push)
    origin  git@github.com:tdyer/wdi_4_rails_hw_tdd_hacker_news.git (fetch)
    origin  git@github.com:tdyer/wdi_4_rails_hw_tdd_hacker_news.git (push)

Push master to Heroku

Only keep clean, working code on master. After you complete a feature, merge it onto master. Push your updated master to GitHub, then to Heroku.

git checkout master
git merge my-feature # merge your working code
git push origin master # update GitHub
git push heroku master # update Heroku

Update Heroku's Database

Once you've deployed your code, you can safely run new migrations. You'll need to do this step every time you have new migrations.

heroku run rails db:migrate

If you have seeds or examples, or if you've updated seeds or examples, you should also run them on Heroku.

heroku run rails db:seed
heroku run rails db:examples

Set your Secrets

Set your environmental variables in your Heroku app.

heroku config:set SECRET_KEY_BASE=$(rails secret)
heroku config:set SECRET_TOKEN=$(rails secret)
heroku config:set CLIENT_ORIGIN=https://yourgithubname.github.io

IMPORTANT NOTE: The URL in the above command must NOT have a trailing slash on the end. If you're experiencing CORS issues, ensure that your CLIENT_ORIGIN variable has no slash on the end.

Check Your Work

Restart your application and check it out in the browser.

heroku restart
heroku open

You'll probably see something like this:

That's normal, unless you have defined a root route.

Change Your App's Name (optional)

If you wish you can rename your app at any time. It must be unique across all apps deployed to Heroku.

heroku apps:rename newname

Your app will become immediately available at it's new subdomain, newname.herokuapp.com.

Share Your App (REQUIRED)

  1. Open a Pull Request on this repository here.
  2. Include the deployed URL of your Heroku app in the Pull Request.

Heroku Command Reference

A full list of Heroku commands can be accessed by running heroku --help; below are some of the more common ones.

Commands Behavior
heroku logs [--tail] Running just heroku logs will show you the server logs from your deployed API. The --tail flag is optional.
heroku run ... Run a program from within Heroku. Examples (heroku run rails console, heroku run rails db:migrate).
heroku config Environmental variables in your current Heroku app.
heroku config:set SECRET_KEY_BASE=$(rails secret) Set Secret Key.
heroku config:set SECRET_TOKEN=$(rails secret) Set TOKEN.
heroku config:set CLIENT_ORIGIN=https://yourgithubname.github.io Set CLIENT_ORIGIN.
heroku apps:rename newname Rename Heroku app name (entirely optional).
heroku restart Restart the Heroku app, make sure you do this after changing your API.
heroku open Open your Heroku app in default browser.
heroku --help Displays a Heroku CLI usage summary.

WARNING: Ephemeral Filesystem

One serious limitation of Heroku is that it provides an "ephemeral filesystem"; in other words, if you try to save a new file inside the repo (e.g. an uploaded image file), it will disappear when your app is restarted or redeployed.

As an example, try running the following commands:

heroku run bash
touch happy.txt; echo 'is happy' > happy.txt
cat happy.txt

Then, hit Ctrl-D to get out of Heroku bash shell. If you re-open the shell and run ls -l, happy.txt will be missing!

The typical workaround is to save files in cloud storage such as Amazon S3; more on this in the near future.

Troubleshooting

These are the commands required for deploying to Heroku with rails. If your Heroku deployment isn't working as expected, review these steps carefully.

  • heroku create
  • git push heroku master
  • heroku run rails db:migrate
  • heroku run rails db:seed
  • heroku config:set SECRET_KEY_BASE=$(rails secret)
  • heroku config:set SECRET_TOKEN=$(rails secret)
  • heroku config:set CLIENT_ORIGIN=https://yourgithubname.github.io
  • heroku apps:rename newname (optional)
  • heroku restart
  • heroku open

If you have successfully deployed your Rails API but are experiencing problems with the production database (note that the production database is entirely separate from your development database), you may find it useful to use the command heroku pg:psql to connect to the production database with the PSQL client. Be cautious though, it's possible to accidentally destroy production data from the CLI.

Additional Resources

License

  1. All content is licensed under a CC­BY­NC­SA 4.0 license.
  2. All software code is licensed under GNU GPLv3. For commercial use or alternative licensing, please contact legal@ga.co.