Setup app on Heroku for a Client

You can do the following when you (hi@briancasel.com) are invited to client's "Team" in Heroku. You only need member permissions (you don't need admin permissions to do the following).

While it's possible to do all of the following using Heroku's CLI and appending --team teamname to all CLI commands, I find it's easier (and safer) to just use Heroku's dashboard to do the following:

Create app(s) for staging and production

If no apps are created in the Heroku Team yet, create them in the interface. Name them appname-staging and appname-production.

Deploy from GitHub

To do the first (and future) deployments, the best option is to connect the GitHub Repo.

Go to the Deploy tab and follow instructions for connecting the GitHub repo for this project to this app.

First deployment + Setting up Dynos

Before you can create any dynos or database, you must do the first deployment.

In the base directory of the project, create a file named Procfile (use capital P and no file extension).

The content can just be this, assuming it's a basic Rails app with no background workers:

web: bundle exec rails server -p $PORT

Commit that to github.

Deploy to Heroku manually in the Deploy tab -> Select the branch to deploy to this app (I typically create a git branch called staging and deploy that branch to the staging site. main branch gets deployed to the production site).

After deployment, you should now see a "Basic" web dyno automatically setup for this app.

Setup Vars & Staging Environment

In Heroku, go to "Settings" -> "Config Vars" and do the following:

If this is the staging app, then change:

  • RAILS_ENV -> change from production to staging

  • RACK_ENV -> change from production to staging

Add an environment variable for RAILS_MASTER_KEY and set its value to the key that is in the project: config/credentials/staging.key

Setup the Postgres Database on Heroku

In Resources -> "Add-ons" -> Find "Heroku Postgres" and add this to the app. It should default to its lowest pricing tier.

(if Rails 8+ and if using Redis instead of solid cable...)

  1. Remove gem 'solid_cable' and add gem 'redis' then bundle install.

  2. Update config/cable.yml to this (replace "appname"):

development:
  adapter: redis
  url: redis://localhost:6379/1

test:
  adapter: test

production:
  adapter: redis
  url: <%= ENV.fetch("REDIS_URL") { "redis://localhost:6379/1" } %>
  channel_prefix: appname_production

Migrate the database using Heroku CLI

Since this is a client's "team" in heroku, we must include the --app flag when running commands.

heroku run rails db:migrate --app appname

Setup Heroku-Data for Redis add-on (for running Sidekiq)

Assuming your app will have background jobs (most do):

Resources -> "Add-ons" -> Find "Heroku Key-Value Store" and add it to the app.

Fix Sidekiq for Heroku

See my notes here. Sidekiq jobs won't work on heroku without this.

Setup TablePlus to connect to the Heroku database

In Heroku -> Resources -> Heroku Postgres -> Settings -> Find all the credentials you'll need when setting up the database connection in TablePlus on Mac.

Update Procfile with additional lines...

  • Add worker (for running sidekiq jobs)

  • Add release command to always run db migrations after deployments.

Now that the database has been setup on Heroku, you can update the Procfile to include the following lines:

web: bundle exec rails server -p $PORT
worker: bundle exec sidekiq
release: bundle exec rails db:migrate

After re-deploying, you should now see 2 dynos: a web and a worker dyno. Turn both to ON.

Restart servers / dynos

After creating all of the above, you'll probably need to restart the dynos in order for everything to work.

In Heroku dashboard -> "More" menu -> "Restart dynos"

Check Heroku logs

You can watch Heroku logs from within Heroku's dashboard by going to "More" menu -> "Logs"

Or you can run this:

heroku run logs -t --app appname

Last updated