A few things should be updated for the relative_url_root docs.

https://guides.rubyonrails.org/configuring.html#deploy-to-a-subdirectory-relative-url-root

Firstly, regarding your point about config.action_controller.relative_url_root - that's what the configuration used to be called in earlier versions of Rails but has been moved to the general application config because it affects a number of areas in Rails - Action Mailer, Assets as well as Action Controller. It seems we missed one place to rename it in the guides and I apologise for that.

config.action_controller.relative_url_root should be changed to config.relative_url_root

config.ru:

map RelativeRoot::Application.config.relative_url_root || '/' do
  run Rails.application
end

There's a very good reason why you need that there and it relates to the CGI environment variables SCRIPT_NAME and PATH_INFO. The former is what you'd consider the relative url root and Rails needs Rack to that set correctly when the app receives call with the request environment hash - if it's not set then you might as well just wrap all your routes in a scope("/sub") { ... } block. Using map creates a Rack::URLMap instance which you can see from the code sets SCRIPT_NAME and PATH_INFO to the desired values. When a Rails application has a mounted Engine (or other Rack app), those values then get adjusted so that you can easily mount them at different URLs without altering the Engine. The SCRIPT_NAME value takes precedence over the relative url config when there is a request context like in a controller but in other contexts like an Action Mailer view or an Active Job task there is no SCRIPT_NAME so there the relative url config is used. I hope this helps you understand the complex interactions at play here - it's not a simple matter of just prefixing config.relative_url_root onto every generated url.

This explanation and the Rack::URLMap example would be an amazing addition to the docs, especially if there was an included section for Puma.

Originally posted by @pixeltrix in #42243 (comment)