heroku-rails-deploy

name: heroku-rails-deploy description: Guides deploying a Strata Rails application to Heroku, covering Node.js and Ruby buildpack ordering, git-subtree push for subdirectory repos, DATABASE_URL migration, AWS startup errors, and Cognito auth adapter bypass.

Heroku Rails Deploy

Overview

Deploys a Strata Rails app to Heroku from a clean state to a running dyno. Covers all non-obvious gotchas specific to Strata apps (Cognito auth, AWS SDK initialization, StaffController eager-loading).

Announce at start: "Using heroku-rails-deploy skill to deploy to Heroku."

Step 1: Verify Heroku CLI Login

heroku auth:whoami

If not logged in, instruct the user: ! heroku login (interactive — must run in user's terminal).

Step 2: Identify Repo Structure

Determine whether the Rails app sits at the git root or in a subdirectory:

git -C <app-path> rev-parse --git-dir

Remember the subdirectory name — used in Step 8.

Step 3: Make Required Code Changes

3a. Create Procfile (if missing)

web: bundle exec puma -C config/puma.rb

3b. Update config/database.yml production section

Replace any AWS RDS IAM auth config with:

production:
  url: <%= ENV['DATABASE_URL'] %>
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
  sslmode: require

Remove aws_rds_iam_auth_token_generator: default — it crashes on Heroku Postgres.

3c. Switch Active Storage to local (if set to :amazon)

In config/environments/production.rb:

config.active_storage.service = :local

S3 requires a provisioned bucket and credentials not available on Heroku.

3d. Create StaffController (if controllers inherit from it)

grep -r "< StaffController" app/controllers/

If results exist and app/controllers/staff_controller.rb is missing, create it:

# frozen_string_literal: true
class StaffController < Strata::StaffController
end

Why: Production Rails eager-loads all files. Missing intermediate base classes crash at boot even if development lazy-loading works fine.

3e. Commit all changes

git add Procfile config/database.yml config/environments/production.rb \
  app/controllers/staff_controller.rb
git commit -m "chore: prepare app for Heroku deployment"

Step 4: Create Heroku App

heroku apps:create [optional-app-name]

Note the app name and git remote URL from output.

If the app is in a subdirectory (Step 2), the heroku remote was added to the wrong directory. Add it manually to the parent repo:

git -C <parent-repo-root> remote add heroku https://git.heroku.com/<app-name>.git

Step 5: Provision Postgres

heroku addons:create heroku-postgresql:essential-0 --app <app-name>

Heroku sets DATABASE_URL automatically — Rails picks it up via config/database.yml.

Step 6: Add Buildpacks (Order Matters)

heroku buildpacks:add heroku/nodejs --app <app-name>
heroku buildpacks:add heroku/ruby --app <app-name>
heroku buildpacks --app <app-name>   # verify: nodejs first, ruby second

Why Node.js first: cssbundling-rails runs css:install during assets:precompile, which requires npm. Adding Node.js with --index 1 after the fact silently drops the Ruby buildpack — always add both explicitly.

Step 7: Set Config Vars

# App won't boot in production without a secret key
SECRET=$(ruby -e "require 'securerandom'; puts SecureRandom.hex(64)")
heroku config:set SECRET_KEY_BASE="$SECRET" --app <app-name>

# AWS SDK loads at startup and requires a region even if AWS features aren't used
heroku config:set AWS_REGION=us-east-1 --app <app-name>

# Bypass Cognito — use mock adapter for non-AWS deployments
heroku config:set AUTH_ADAPTER=mock --app <app-name>

AUTH_ADAPTER values:

• mock — no AWS required, accepts any credentials, auto-creates users on first login
• cognito — requires COGNITO_CLIENT_ID, COGNITO_CLIENT_SECRET, COGNITO_USER_POOL_ID

Step 8: Deploy

App at git root:

git push heroku main

App in subdirectory <subdir>/ inside parent repo:

git -C <parent-repo-root> subtree push --prefix <subdir> heroku main

Watch for Released vN and deployed to Heroku at the end. If asset precompile fails, check Common Pitfalls.

Step 9: Post-Deploy

heroku ps:scale web=1 --app <app-name>
heroku run rake db:migrate --app <app-name>
heroku open --app <app-name>

Verify the dyno is up (not crashed):

heroku ps --app <app-name>
heroku logs --num 30 --app <app-name>

Common Pitfalls