Debug Rails Deployments

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

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 key in config/master.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