Rails deployment to servers you own

Build steps it runs

1. Installs the Ruby version from .ruby-version, .tool-versions, or Gemfile.lock
2. Installs the matching Bundler version and your gem dependencies
3. Runs assets:precompile if your app has it — skipped automatically for API-only apps
4. Runs db:migrate on the cron server, so migrations happen exactly once per deploy

Processes it adds

Created on your first deploy, then kept alive and restarted on every deploy after.

bin/rails server -b 127.0.0.1 -p $PORT   # web
bin/jobs                                 # added if Solid Queue is detected
bundle exec sidekiq                      # added if Sidekiq is detected

Caddy reverse proxies to the web process and load balances across your web servers. Add or scale processes yourself whenever you need to.

Environment variables you set

Added in Hatchbox and written into every release.

RAILS_MASTER_KEY=<contents of config/master.key>
DATABASE_URL=postgres://user:pass@host/db_name

Attach a Postgres or MySQL database in Hatchbox and it sets DATABASE_URL for you. With Solid Cache, Solid Queue or Solid Cable in your Gemfile.lock, each deploy also creates their databases beside it and sets CACHE_DATABASE_URL, QUEUE_DATABASE_URL and CABLE_DATABASE_URL.

Deploy on push, from CI, or by hand

With auto deploy on, every push to your branch starts a deploy through the GitHub webhook. Prefer to deploy only after your tests pass? Turn auto deploy off and call your app's deploy webhook URL from the last step of your CI pipeline instead. The Deploy button in the dashboard always works too.

Health checks after every restart

Behind a load balancer, Hatchbox waits after each web server restarts for your app to answer its health check path before restarting the next, so no two servers are down at once. If the app doesn't answer within two minutes the deploy is marked as failed and the remaining servers keep serving the previous release. Rails 7.1+ apps have their /up route detected on their first deploy; set a health check path in the app's Caddy settings otherwise. Without one, the deploy waits for the app to answer at all. Set the HATCHBOX_WAIT_FOR_HEALTH_CHECK environment variable to wait on a cluster without a load balancer, or to false to turn the wait off.

# config/routes.rb (Rails 7.1+ ships this route)
get "up" => "rails/health#show", as: :rails_health_check

Hooks for after a deploy, or after a failed one

Commit an executable .hatchbox/post-deploy script to run a task once, on one server, after each successful deploy. Notify Slack, warm a cache, or kick off a data backfill. A .hatchbox/failed-deploy script runs when a deploy fails.

#!/usr/bin/env bash
# .hatchbox/post-deploy
set -e
bin/rails runner 'Rails.cache.clear'

One-click rollbacks

Every deploy is kept in your app's history with its commit and full log. If a release misbehaves, hit Rollback on an earlier deploy and Hatchbox redeploys that commit. No shell session or git revert needed.