That's a good question! Judging by some of the answers here and elsewhere, there seems to be a general lack of understanding of how the Apache reverse proxy settings affect the Mojolicious application and what the hook is supposed to do.
You've received an answer that's basically correct, but it begins with "Maybe [need to replace server proxy pass..." and it doesn't provide any explanation. A trial-and-error approach may or may not work for you. If your hook works differently, it probably won't.
Apache reverse proxy
This is your reverse proxy configuration (trailing slash removed, see below):
ProxyPass /app1 http://localhost:3000 keepalive=On
Quoting from the Apache documentation:
Suppose the local server has address http://example.com/; then
| ProxyPass /mirror/foo/ http://backend.example.com/
will cause a local request for http://example.com/mirror/foo/bar to be internally converted into a proxy request to http://backend.example.com/bar.
Now, assuming your Apache is listening on localhost:80 and your (Morbo) application server is listening on port 3000, a request to http://localhost/app1 is received by the Apache and forwarded to your application as /. The app1 prefix has been lost, which is why it's missing from the base url, i.e., it's missing in all the links. To fix urls generated by the application, this prefix must be added to the base url, which leads us to the hook.
Hook
This is your hook function:
if ($self->req->headers->header('X-Forwarded-Host')) { # 1. if
my $path = shift @{$self->req->url->path->parts}; # 2. shift
push @{$self->req->url->base->path->parts}, $path; # 3. push
}
This hook is supposed to fix the base url. As explained above, the app1 prefix needs to be added to the base url, which is prepended to all generated urls. If one of your templates links to /test, the base url should look like /app1 to get the final url /app1/test.
This is what your hook does:
By checking for the X-Forwarded-Host, you make sure to only modify the base url if the request came through the reverse proxy. This works because the mod_proxy_http module (documentation) automatically sets that header. Without that check, you wouldn't be able to access your application server directly under localhost:3000, all urls would be broken.
In fact, I asked the question on how this distinction should be made in a reliable way to fix the url prefix when using a reverse proxy without breaking requests going to the application server. Unfortunately, most of the answers I have received are wrong. But I believe checking for X-Forwarded-Host is good enough as it's set by Apache and not by Morbo or Hypnotoad. In fact, it's set by reverse proxies, which is precisely what you're looking for.
This shift is supposed to extract the prefix from the request url.
This is necessary because, strictly speaking, appending the application prefix to the ProxyPass directive manipulates the final request url, so your application receives a request for /app1/. Of course, there's no route for that address because the router in your application doesn't know that /app1 is the prefix of that instance rather than a relative application url.
Clearly, adding the hard-coded prefix /app1 to all templates (as some might be tempted to do) would not work if you deployed another copy of the same application under /app2. Even if you didn't, you'd still have to change all the links if your provider forces you to change the app1 prefix to app_one. This is why the prefix is picked up in that hook, stored to make links work (see #3) and then removed from the request url to make the router happy.
This is where the /app1 prefix, a single path token, is appended to the base url. The base url is prepended to urls generated in your templates. This is what turns /test into /app1/test (if the request came through the reverse proxy).
In your case, /test is turned into //test because you're missing the prefix. I've explained that at the end of this answer.
Fix reverse proxy
That being said, your reverse proxy needs to manipulate the request url to include the prefix in order to make the hook work:
ProxyPass /app1 http://localhost:3000/app1
After this modification, your hook works:
It modifies the base url only if a reverse proxy header is set because the modification is only necessary when a reverse proxy is used.
All requests going to the Mojolicious application will have the /app1 prefix, e.g., /app1/test. In this step, the prefix is removed to turn the url into /test.
The prefix removed in step 2 is appended to the base url, which is later used to generate links.
This should explain why you need to add the application prefix to the ProxyPass line. Without that explanation, someone else might try to do just that without success because they might have a different hook function.
Slashes
A single slash can break everything and cause most requests to fail with error 404.
Note that the local target url in your ProxyPass line (second argument) has a trailing slash but the path argument doesn't. If those don't match, you might end up with double slashes in the request url and some requests could fail.
From the Apache documentation:
If the first argument ends with a trailing /, the second argument should also end with a trailing /, and vice versa. Otherwise, the resulting requests to the backend may miss some needed slashes and do not deliver the expected results.
Now, if you remove the trailing slash but forget the prefix...
ProxyPass /app1 http://localhost:3000
... generated urls will still have two leading slashes: url_for '/test' = //test
That's because you're appending undef to the base url where you want to append the application prefix.
What happens is that in step 2 (see above), you extract the prefix, assuming the application is running exactly one level below the document root, i.e., your prefix is something like app1 and not apps/app1 (in which case the shift/push routine has to be run twice). But there's no prefix in the ProxyPass directive, so your application sees something like /, in other words, there's nothing to extract from parts. And there's no safeguard in the code either, so you end up pushing undef to the parts array of the base url. If you then generate a url, Mojolicious is adding an extra slash for that undef element, which is why you get //test. The parts array looks like this:
"parts" => [
undef,
"test"
],
To fix this double slash error, you can add a safeguard to your hook:
my $path = shift @{$self->req->url->path->parts};
if ($path) { # safeguard
push @{$self->req->url->base->path->parts}, $path;
}
Of course, as long as your reverse proxy configuration has the prefix in it, $path should always be defined.
One could certainly argue that this approach is a hack because it manipulates the url. Hacks tend to fail under certain circumstances. In this case, it would fail if you were to manually set the X-Forwarded-Host while accessing the application server directly. I mentioned that in my question. But as developer, you're probably the only person who has direct access to that application server, as the firewall would only allow external requests to the reverse proxy in a typical production environment. I'll leave it at that.
