Prerequisites#

• Ensure you are running Ruby 3.4.5 or later.
• Upgrade PostgreSQL to version 17+ for optimal compatibility and performance.
• Ensure Redis is installed and accessible for caching and Action Cable (production).
• Back up your application code, databases, and configuration files before starting the upgrade.

Upgrade Steps#

1. Update Gemfile Dependencies#

Replace Rails and asset pipeline dependencies:

gem "rails", "~> 8.1.3"
gem "propshaft", ">= 1.1"
gem "store_model", "~> 4.5"
# gem "administrate-field-enum", ">= 0.0.9" # Remove or comment out, incompatible with Rails 8

Security Note: Keep Rails updated to the latest patch version for security fixes. Rails 8.1.3 includes bug fixes and improvements to Active Support, Active Model, and other components.

Remove sprockets-rails and any related Sprockets gems. Upgrade Puma to 6.0+ if not already done. Upgrade store_model from 2.4.0 to 4.5.0. Upgrade mcp (Model Context Protocol Ruby SDK) from 0.8.0 to 0.9.2, which includes:

• MCP::Client::Stdio transport support for command-line integration
• Progress notifications per MCP specification
• CORS support for browser-based MCP clients with SSE connections
• Bug fixes for SSE connection handling and duplicate connection rejection (409 status)

Run:

bundle install

2. Asset Pipeline Migration: Sprockets to Propshaft#

Remove Sprockets-specific configuration and files. Update or create the following:

• config/initializers/assets.rb:
  ⧉

  Rails.application.config.assets.version = "1.0"
  # No precompile list needed; Propshaft includes all assets by default
  

• app/assets/config/manifest.js:
  ⧉

  /*
   * Propshaft Asset Manifest
   * Propshaft automatically includes all assets in app/assets, vendor/assets, and lib/assets.
   * No explicit linking required like Sprockets.
   */
  

Propshaft will automatically serve all assets from the standard asset directories. Remove any manual precompile directives or explicit asset linking.

Bootstrap Icons Font Loading#

If you use Bootstrap icons, update your SCSS to load fonts directly from node_modules:

$bootstrap-icons-font-path: "~bootstrap-icons/font/fonts";
@import "~bootstrap-icons/font/bootstrap-icons";

Ensure dartsass-rails is configured with --load-path=node_modules. No need to copy font files into app/assets—they are served directly from node_modules [source].

3. Configure Redis for Caching and Action Cable#

Cache Store Configuration#

Configure production caching in config/environments/production.rb:

config.cache_store = :redis_cache_store, {
  url: ENV.fetch("REDIS_URL", "redis://localhost:6379/0"),
  pool: false
}

Action Cable Configuration#

Configure Action Cable in config/cable.yml:

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

Redis provides a simpler deployment model for production environments compared to database-backed solutions, with no additional database schemas required.

4. Update Application Configuration#

In config/application.rb:

• Set Rails defaults to 8.1:
  ⧉

  config.load_defaults 8.1
  

• Retain custom configurations such as:
  • config.autoload_paths << Rails.root.join("app/components") for ViewComponent
  • config.time_zone = "Eastern Time (US & Canada")
  • config.middleware.use Rack::Deflater
  • config.active_job.queue_adapter = :sidekiq
  • config.autoload_lib(ignore: %w[assets tasks])

5. Dashboard Enum Field Updates#

If you previously used administrate-field-enum, replace enum fields in dashboards with the built-in Field::Select:

operating_system: Field::Select.with_options(collection: Agent.operating_systems.keys)
role: Field::Select.with_options(collection: ProjectUser.roles.keys)

Remove or comment out any usage of Field::Enum or the administrate-field-enum gem [source].

6. Store Model Upgrade#

Upgrade store_model from version 2.4.0 to 4.5.0 (implemented in PR #619), which includes the following changes:

• Major version upgrade from 2.x to 4.x with breaking changes
• Minimum ActiveRecord requirement increased from >= 5.2 to >= 7.0
• Key new features in 4.x versions:
  • Validation hooks functionality (4.5.0)
  • ActiveModel 8.1+ normalization support (4.4.0)
  • Union types and hash type support for storing keyed collections (4.3.0)
  • Improved accepts_nested_attributes_for functionality (4.2.0)

No application code changes are typically required for existing store_model usage, but review any custom StoreModel implementations for compatibility with the updated gem.

7. Database Configuration#

Update config/database.yml for production PostgreSQL settings. Enhance PostgreSQL settings for statement timeout, idle transaction timeout, connection reaping, and enable prepared statements.

8. Test Suite and Devise Integration#

For Devise compatibility in tests, add to your test setup:

Warden.test_mode!
Rails.application.reload_routes!

This resolves "Could not find a valid mapping" errors in request specs.

9. Asset Compilation for Production#

Run:

rails assets:precompile

Ensure DATABASE_URL and REDIS_URL environment variables are set for production.

Breaking Changes#

• Sprockets precompile directives are obsolete; Propshaft includes all assets automatically.
• Enum fields in dashboards must use Field::Select with an explicit collection.
• store_model upgraded from 2.x to 4.x; minimum ActiveRecord requirement is 7.0.
• Production environments use Redis for caching and Action Cable instead of database-backed solutions.
• Bootstrap icons are loaded directly from node_modules via SCSS; no asset copying required.

Rollback Procedure#

If you need to revert to Rails 7.2:

1. Revert Gemfile changes:
   ⧉

   gem "rails", ">=7.2", "<8.1"
   gem "sprockets-rails"
   gem "store_model", "~> 2.4"
   # Remove: propshaft
   # Re-enable: administrate-field-enum
   

2. Restore configuration files from git:
   ⧉

   git checkout origin/main -- config/application.rb config/environments/ config/database.yml
   

3. Revert dashboard changes:
   ⧉

   git checkout origin/main -- app/dashboards/
   

4. Revert test configuration:
   ⧉

   git checkout origin/main -- spec/rails_helper.rb
   

5. Run:
   ⧉

   bundle install
   

6. Restore asset manifest:
   ⧉

   git checkout origin/main -- app/assets/config/manifest.js
   

Verification Steps#

• Confirm the application boots successfully.
• Run the full test suite; all tests should pass.
• Verify API endpoints for backward compatibility.
• Test Devise authentication.
• Check that the asset pipeline serves assets correctly.
• Ensure the admin dashboard functions and enum fields display as expected.
• Confirm Bootstrap icons render properly [source].

Notes on Controller Strong Parameters#

No specific changes to strong parameter handling are required for Rails 8.1 unless your application uses new features or customizations not covered here. Review your controllers for any deprecated patterns, but standard strong parameter usage remains valid.

For further details and troubleshooting, refer to the in-repo upgrade notes and configuration files.