Update `relative_url_root` docs

[arianf]

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 https://github.com/rails/rails/issues/42243#issuecomment-842747962

[rails-bot[bot]]

This issue has been automatically marked as stale because it has not been commented on for at least three months. The resources of the Rails team are limited, and so we are asking for your help. If you can still reproduce this error on the 7-0-stable branch or on main, please reply with all of the information you have about it in order to keep the issue open. Thank you for all your contributions.