fix: server and admin url configuration

[wladyslawczyzewski]

Hi. While trying to launch Strapi 5 for my new website in subpath configuration I noticed that isn't working. Turns out that others also have issues with this. I did some investigation and found that configuration is not loaded properly causing the issues when launching Strapi in subpath configuration (e.g. https://domain.com/cms).

What does it do?

1. update the logic to load the correct admin.path based on admin.url (admin.path is required in build context to set the ctx.basePath which is used to put the resources for admin panel)
2. fix the prefix value for admin panel's APIs
3. fixed configuration loading, as config object is mutable, so using it for setting server.absoluteUrl and admin.absoluteUrl should be done before mutating the config object in loadConfiguration function

Why is it needed?

Strapi 5 when running in subpath of the main website domain is not working.

How to test it?

Tested on local machine by checking the admin panel load correctly with different pair of configuration for server.url and admin.url:

server.url	admin.url	working?
http://localhost:1337	undefined	✅
http://localhost:1337	http://localhost:1337/admin	✅
http://localhost:1337	/admin	✅
http://localhost:1337	/dashboard	✅
http://localhost:1337	http://localhost:1337/dashboard	✅
http://localhost:1337	http://localhost:1337/cms/dashboard	❌ (to fix this case I think we need to introduce new config key admin.path)
http://localhost:1337/cms	undefined	✅
http://localhost:1337/cms	http://localhost:1337/cms/admin	✅
http://localhost:1337/cms	/admin	✅
http://localhost:1337/cms	/dashboard	✅
http://localhost:1337/cms	http://localhost:1337/cms/dashboard	✅
/cms	undefined	✅
/cms	http://localhost:1337/cms/admin	✅
/cms	/admin	✅
/cms	/dashboard	✅
/cms	http://localhost:1337/cms/dashboard	✅
/cms	http://localhost:1337/dashboard	❌
undefined	undefined	✅
undefined	http://localhost:1337/admin	✅
undefined	/admin	✅
undefined	/dashboard	✅
undefined	http://localhost:1337/dashboard	✅
undefined	http://localhost:1337/cms/dashboard	❌

Related issue(s)/PR(s)

Related issues:

#21452 #21479

NB. For Strapi 5 when it's run in subpath configuration (http://domain.com/cms) if you used reverse proxy like NGINX - you don't need to rewrite the request uri, just pass the request to the Strapi's instance origin/upstream.

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
contributor-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Oct 17, 2024 0:15am

[strapi-cla]

All committers have signed the CLA.

[wladyslawczyzewski]

Updated the test cases in the PR description. Looks like at this moment there's no chance to run the Strapi admin panel in different subpath not related to the server.url.

[hanpaine]

Hi @wladyslawczyzewski thanks for your contribution - we'll take a look very soon 🙏

[innerdvations]

Thanks for the PR and even moreso for the detailed information! I'll check this out and hopefully we will get it merged soon.

In the meantime, could you fix the reported linting errors?

  /home/runner/work/strapi/strapi/packages/core/core/src/configuration/urls.ts
    2:10  error  'strings' is defined but never used  @typescript-eslint/no-unused-vars

  /home/runner/work/strapi/strapi/packages/core/core/src/services/server/admin-api.ts
    10:66  error  Unnecessary escape character: \/  no-useless-escape

[wladyslawczyzewski]

hi @innerdvations , thanks for your review – I've fixed the lint errors, could you please check one more time?

[hanpaine]

@innerdvations looks like this could be an issue on V4 too - can you check if so, and dupe to v4 please?

[innerdvations]

@innerdvations looks like this could be an issue on V4 too - can you check if so, and dupe to v4 please?

I think @alexandrebodin and @Convly are sorting out the discrepencies between the two, but if not then I'll do it

[raphaelbadawi]

The fix works fine on production for me, but I noticed that the media library assets links are broken in the admin panel context. Not sure why it does that, for now I workaround this with a nginx rewrite rule (which is weird since I don't need rewrite rules for the admin panel itself).

[derrickmehaffy]

The fix works fine on production for me, but I noticed that the media library assets links are broken in the admin panel context. Not sure why it does that, for now I workaround this with a nginx rewrite rule (which is weird since I don't need rewrite rules for the admin panel itself).

That's probably the security middleware csp settings, you'll need to set those.

[mad-zephyr]

Hello, colleagues. Sorry for bother you. Could someone kindly give updates related to this bug fix, any plans to merge it? As far as I know it almost ready for merging.

[hanpaine]

Hi all, thanks for your patience on this work - we'll be re-picking it up this week 🙏

[Matb85]

Hello, any updates on when this will be merged?

[alexandrebodin]

Hello all,

To share some context,

Right now this PR cannot be merged. It does seem to work but it does so by adding internal prefixing, which creates unexpected behaviors. The goal in the short term is to offer a way to make strapi work behind a reverse-proxy like we supported in v4.

To be fully transparent we have a dedicated workshop tomorrow on it 🙏

[Moonlight63]

I wonder how that's going.

[Convly]

Hey, we took some time to go over this with @alexandrebodin and test the different scenario + decide where we wanted to go.

1st, you can find below a table you shared in your original PR that we completed (on top of the result for your PR) with the behavior in v4 (pre vite update) + the behavior when using Alex's PR.

server.url	admin.url	Community PR	v4.16 (❌ <=> requires reverse proxy)	PR Alex
http://localhost:1337	undefined	✅	✅	✅
http://localhost:1337	http://localhost:1337/admin	✅	✅	✅
http://localhost:1337	/admin	✅	✅	✅
http://localhost:1337	/dashboard	✅	✅	✅
http://localhost:1337	http://localhost:1337/dashboard	✅	✅	✅
http://localhost:1337	http://localhost:1337/cms/dashboard	❌	✅	✅
http://localhost:1337/cms	undefined	✅	❌	❌ (vite serves too many things / TBF later)
http://localhost:1337/cms	http://localhost:1337/cms/admin	✅	❌	same as above
http://localhost:1337/cms	/admin	✅	❌	same as above
http://localhost:1337/cms	/dashboard	✅	❌	same as above
http://localhost:1337/cms	http://localhost:1337/cms/dashboard	✅	❌	same as above
/cms	undefined	✅	❌	same as above
/cms	http://localhost:1337/cms/admin	✅	❌	same as above
/cms	/admin	✅	❌	same as above
/cms	/dashboard	✅	❌	same as above
/cms	http://localhost:1337/cms/dashboard	✅	❌	same as above
/cms	http://localhost:1337/dashboard	❌	❌	same as above
undefined	undefined	✅	✅	✅
undefined	http://localhost:1337/admin	✅	✅	✅
undefined	/admin	✅	✅	✅
undefined	/dashboard	✅	✅	✅
undefined	http://localhost:1337/dashboard	✅	✅	✅
undefined	http://localhost:1337/cms/dashboard	❌	✅	✅

As you can see, your PR allows to handle far more possibilities while Alex's make it ISO with what we had in v4.

After discussing it, we came to the conclusion that our goal with setting server URLs is to match reverse proxies configurations rather than automatically modifying how we serve our APIs.

Handling the proxying ourselves could cause breaking change issues for plugin maintainers depending on constant endpoints as well as for users, whereas delegating the server URL redirection to a reverse proxy allows for more flexibility.

To summarize, we will move forward with Alex's PR for now to keep consistency & flexibility with v4, but we're open to discuss a feature request around setting the server URL & handling the paths directly in Strapi.

Below I'm sharing a very simple caddy file that we used for our tests & that create a reverse proxy on localhost:1338/cms -> localhost:1337.

:1338

handle_path /cms/* {
	uri strip_prefix /cms
	reverse_proxy localhost:1337
}

respond "Not Found" 404

log logger {
	output stdout
	format console
}

[wladyslawczyzewski]

hi @Convly thanks for detailed explanation. I see your point and I totally trust you in such decisions as you're both the maintainers of this project and you know better this project then me (it was actually my first time I ran strapi).

Using reverse proxy is a quite good solution and I think it's good option for the most use cases, however, there're situations where the reverse proxy can't do url rewrites, for instance, AWS' Load Balancers - so there's no option to run the strapi in subpath and subdomain installation is only way to get that work.

Feel free to close this PR as soon as you decide the issue is solved.

[Convly]

Interesting, I haven't used AWS ALBs in a long time, but isn't it possible to place a reverse proxy in between your ALB & your application server? Otherwise, I believe it's possible to do full redirects for simple use cases

In the meantime, I'll close this PR just so that it's removed from our backlog. Thanks for your contribution, greatly appreciated!

[alexandrebodin]

@wladyslawczyzewski definitly make a feature request with the explanation of your usecase that won't work with the reverse proxy so the product team can see it 🙏

[Moonlight63]

I guess I am confused about how to make a correct configuration for serving the admin panel on a different subdomain from the api server given the double / bug that this PR seems to have partially fixed. I have been trying for a few days to off and on to get my strapi instance to server at api.example.com, and put the admin panel on admin.example.com, but it seems like this is not possible because that requires the admin panel to be pointing to root /, which doesn't work. If I host the admin panel at admin.example.com/admin, then everything is fine of course, but that is not the goal. Are we just saying flat out that this use case or setup is not and will not be supported/possible? I am doing this using a "different servers" config, hosting the built admin SPA in a simple nginx server. Edit: It's even more irritating given that I could just set a full domain name as the url for the admin panel, which would solve the issue entirely, but the fqdn gets parsed out to a relative path anyway so it doesn't work.

[alexandrebodin]

I guess I am confused about how to make a correct configuration for serving the admin panel on a different subdomain from the api server given the double / bug that this PR seems to have partially fixed. I have been trying for a few days to off and on to get my strapi instance to server at api.example.com, and put the admin panel on admin.example.com, but it seems like this is not possible because that requires the admin panel to be pointing to root /, which doesn't work. If I host the admin panel at admin.example.com/admin, then everything is fine of course, but that is not the goal. Are we just saying flat out that this use case or setup is not and will not be supported/possible? I am doing this using a "different servers" config, hosting the built admin SPA in a simple nginx server. Edit: It's even more irritating given that I could just set a full domain name as the url for the admin panel, which would solve the issue entirely, but the fqdn gets parsed out to a relative path anyway so it doesn't work.

We are only prioritizing another PR not leaving the issue open. We shared the experimental version in the original issue you can find it here for testing. It should work like the v4 with a reverse proxy configuration. https://github.com/strapi/strapi/issues/21184#issuecomment-2490644833

[alexandrebodin]

For any further discussion please go to https://github.com/strapi/strapi/issues/21184 so we have a single source of truth for the issue 🙏