Documentation of relative root deployment setup

[dssjoblom]

Description

It seems like the documentation (https://guides.rubyonrails.org/configuring.html#deploy-to-a-subdirectory-relative-url-root) for setting up relative root deployments is lacking. In some (most?) cases, it is not enough to specify the RAILS_RELATIVE_URL_ROOT variable, but you have to make changes to config.ru and occasionally modify SCRIPT_NAME as well.

Expected behavior

Setting the RAILS_RELATIVE_URL_ROOT environment variable should automatically use the specified subdirectory in all cases, without requiring further setup.

Actual behavior

1. Engine paths are created incorrectly. MyEngine::Engine.routes.url_helpers.xyz_path does not include the root prefix. This can be fixed by doing Rails.application.routes.default_url_options[:script_name] = ENV['RAILS_RELATIVE_URL_ROOT'] before the routes are generated, but this is not documented anywhere, nor is it clear why it works.

2. In most use cases, you need to modify config.ru so that the application routes end up using the prefix as well:

map ENV['RAILS_RELATIVE_URL_ROOT'] || '/' do
  run Rails.application
  Rails.application.load_server
end

System configuration

Rails version: 6.1.4.7

Ruby version: 2.7.6p219

[ghiculescu]

It seems like there was a previous attempt to improve docs around this but it didn't get much traction. See https://github.com/rails/rails/issues/42248 / https://github.com/rails/rails/pull/42303

Would you be interested in making a PR to improve the docs? (Or, if it's possible and make sense, to resolve the issues entirely)

[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.