Debug Rails Deployments

This guide covers common issues and solutions encountered when deploying Ruby on Rails applications, especially during the first deployment.

Minimum Env Variables

Example of the env variables that Rails apps usually use:

RAILS_ENV=production
RAILS_MASTER_KEY=value
SECRET_KEY_BASE=value
DATABASE_URL=postgresql://user:pass@host:5432/demo
# If using the db for cable, cache and queue
# gems: solid_cable solid_cache solid_queue
CABLE_DATABASE_URL=postgresql://user:pass@host:5432/demo_cable
CACHE_DATABASE_URL=postgresql://user:pass@host:5432/demo_cache
QUEUE_DATABASE_URL=postgresql://user:pass@host:5432/demo_queue

Notes:

• RAILS_MASTER_KEY: Decrypts credentials file, eg: config/credentials/production.yml.enc Allows Rails to read secrets. To get the value cat config/credentials/production.key
• SECRET_KEY_BASE: Signs/encrypts cookies & sessions. Keeps cookies, sessions, CSRF tokens secure. Can use rails secret to generate a new value.

More debugging tips below:

Common First Deployment Checklist & Issues

Here are frequent problems and configuration points to check:

1. Credentials & Master Key

• Error: ActiveSupport::MessageEncryptor::InvalidMessage
• Cause: This usually means the RAILS_MASTER_KEY environment variable is missing or incorrect in your production environment. Rails cannot decrypt config/credentials/production.yml.enc without the correct key.
• Solution:
  • Ensure the RAILS_MASTER_KEY environment variable is set correctly in your production server/hosting environment. You can find the value for the in config/production.key (do not commit this file!).
  • If you haven’t initialized encrypted credentials for production, run:

    rails db:encryption:init
    

  • To edit production credentials:

    EDITOR="code --wait" bin/rails credentials:edit --environment=production
    

  • Commit the generated config/credentials/production.yml.enc file.

2. Secret Key Base

• Error: Application might fail to start or session errors might occur.
• Cause: Rails requires a SECRET_KEY_BASE environment variable for signing sessions and other security features. Some platforms (like Heroku buildpacks) might generate a temporary one during the build, which won’t match the one expected by your running application if you’ve set one in your credentials.
• Solution: Ensure the SECRET_KEY_BASE environment variable is explicitly set in your production environment. You can generate a suitable key using bin/rails secret and store it securely (often in your production credentials or directly as an environment variable).

3. Host Authorization

• Error: Blocked host: ... or ActionDispatch::HostAuthorization::DefaultResponseApp errors in logs, potentially leading to HTTP 403 Forbidden pages.
• Cause: Rails has a security feature preventing DNS rebinding attacks by only allowing requests from explicitly permitted hostnames.

• Solution: Configure allowed hosts in config/environments/production.rb:

  # config/environments/production.rb
  config.hosts = [
    "your_domain.com",       # Your primary domain
    "www.your_domain.com",   # Optional: www subdomain
    # Add any other domains or subdomains that should access your app
    # You can also use regular expressions:
    # /\.example\.com$/ # Allows any subdomain of example.com
  ]
  
  # If testing without SSL initially, you might temporarily clear hosts,
  # but **do not leave this in production**:
  # config.hosts.clear
  

4. SSL Configuration

• Initial Testing: When first deploying, you might temporarily disable SSL enforcement to simplify debugging connectivity issues. Remember to re-enable SSL for production.

• Configuration (config/environments/production.rb):

  # Temporarily disable for initial tests (NOT recommended for live production):
  # config.force_ssl = false
  
  # Standard Production Settings:
  config.force_ssl = true
  
  # If behind a proxy that handles SSL termination:
  # config.assume_ssl = true
  

Database Setup

• Requirement: The production database needs to be created, migrated, and potentially seeded.
• Commands: Run these on your production server or via your deployment process:

  RAILS_ENV=production rails db:create
  RAILS_ENV=production rails db:migrate
  RAILS_ENV=production rails db:seed # Optional
  

  You can add these to your Procfile release process.

Troubleshooting Tools

When debugging deployment issues, check the following:

• Rails Application Logs: If you app is logging to stdout, then they will show up Blossom App Logs UI for debugging.

Useful Commands

• Build with Buildpacks (Example): You can install the pack tool and try building it on your own machine for debugging.

  pack build test --path . --builder heroku/builder:24
  

• Check Production Credentials:

  rails credentials:show -e production