Deployment guidance of Hosted Blazor WASM under a sub-path

[LeaFrock]

I have a hosted blazor wasm app, and I want to deploy it under a sub-path like https://xxx.mydomain.com/blazor , with nginx.
I've deployed the blazor app on the server(127.0.0.1:5001) and finished the nginx configurations like below,

location /blazor {
            proxy_pass http://127.0.0.1:5001;
            limit_req  zone=one burst=60 nodelay;
        }

A hosted blazor wasm has two parts, server side(web api) and client side(blazor wasm). On the server side, I've configured UsePathBase("/blazor") in Startup.cs. If it's just a ASP.NET Core Web API app, it works. But the blazor app returns a lot of 404 http code of static files as the broswer still visits them with urls like https://xxx.mydomain.com/assets/xxx instead of https://xxx.mydomain.com/blazor/assets/xxx.

I've read issues like #14999 or #15464, but still not find a perfect answer. I think a related doc is required.
Any help? Thanks in advance!

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: be59faf1-5a20-b7e9-19ff-06589023bb15
• Version Independent ID: 250e7458-3c1d-0117-261d-c03ac136f16a
• Content: Host and deploy ASP.NET Core Blazor WebAssembly
• Content Source: aspnetcore/blazor/host-and-deploy/webassembly.md
• Product: aspnet-core
• Technology: aspnetcore-hostdeploy
• GitHub Login: @guardrex
• Microsoft Alias: riande

[guardrex]

Hello @LeaFrock ... In the client app of the hosted WASM app, did you set the base path in wwwroot/index.html:

<base href="/blazor/">

Also, see the NOTE about configurung Static File Middleware to serve static files (CSS, JS) in ...

https://docs.microsoft.com/en-us/aspnet/core/blazor/host-and-deploy/?view=aspnetcore-6.0&tabs=visual-studio#app-base-path

Sometimes, apps also need additional configuration to change the paths for static files but avoid changing the path to the Blazor script. Not every hosting situation requires that, but some do. That NOTE cross-links to the Blazor Static Files topic. See the third bullet of ...

https://docs.microsoft.com/en-us/aspnet/core/blazor/fundamentals/static-files?view=aspnetcore-6.0#blazor-server-file-mappings-and-static-file-options

That hosting scenario where the Static File Middleware must NOT interfere with serving the Blazor script isn't something that I'm very familiar with given that I usually work with and test on IIS/Azure App Service, and IIS/Azure hasn't required it in my experience. Devs have reported that they needed to use that code in reverse proxy scenarios on other hosts, and I know that some of them were using Linux (Nginx and/or Apache). Keep that in mind if you see static files coming down to the app but the Blazor script request getting a 404 on the client.

WRT carrying a topic specific to hosting Blazor in a sub-app scenario ... maybe so. When configuration is challenging but can be called out for common scenarios, such topics have been valuable for devs. Even if that advice ☝️ leads to a working sub-app for you, leave this issue open. I'll take this up with management in early 2022. We're going to continue to be busy 🏃😅 for the next few weeks (e.g., I'm still mopping up 6.0 issues, including NRT warnings work for 6.0), then the 🎁 holiday vacation ⛄ will hit.

Lastly, I'm not expert in Linux hosting scenarios. I merely dabble in it from time-to-time for documentation purposes. I recommend if you're having trouble with configuration to hit up devs on public support forums. We recommend the usual places ...

• Stack Overflow (tag: blazor)
• ASP.NET Core Slack Team
• Blazor Gitter

If you come up with a working configuration (app & server), please come back to this issue and leave a comment with the full configuration (app & server). If this issue goes forward into a dedicated topic and your guidance becomes part of the published article, we can offer you byline credit, which some devs find helpful for professional purposes.

[LeaFrock]

Thank you very much @guardrex ! I'll try your advice and give you feedback next week.

Devs have reported that they needed to use that code in reverse proxy scenarios on other hosts, and I know that some of them were using Linux (Nginx and/or Apache).

Yep, I think it deserves a specific topic.

If you come up with a working configuration (app & server), please come back to this issue and leave a comment with the full configuration (app & server).

I'm glad to do so.

[LeaFrock]

I'm back. What a busy month... sorry for the delay😅.

Nginx

location /blazor {
        proxy_pass         http://0.0.0.0:5000;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        limit_req zone=one burst=60 nodelay;
        # ....... (Skipped)
    }

ASP.NET Core(Backend)

Startup

using Microsoft.AspNetCore.HttpOverrides;

// ......(Skipped)

app.UseForwardedHeaders(new ForwardedHeadersOptions
{
    ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto
});
app.UsePathBase("/blazor");

// It seems that no specific static-file-options are required. `app.UseStaticFiles()` works well.

Hosted Blazor WASM(Fontend)

index.html

<base href="/blazor/">

Route

All links must be like ./xxx or xxx. For example,

<!-- Go to "{your domain}/blazor/account"-->

<!-- valid -->
<a href="./account"> 
<a href="account"> 

<!-- invalid -->
<!-- The browser will go to "{your domain}/account", then Nginx won't handle it-->
<a href="/account"> 

So NavigationManager and HttpClient does.

private readonly HttpClient _client;

// ......(Skipped)

public async Task QueryAsync()
{
        // If the backend API is : {your domain}/blazor/api/account
        var rsp = await  _client.GetFromJsonAsync("api/Account"); // Success
        var rsp = await  _client.GetFromJsonAsync("/api/Account"); // Fail
        // ......(Skipped)
}

[guardrex]

Thanks @LeaFrock ... That's excellent. 👍 Thanks for posting that.

This is currently scheduled for '22. After the holiday vacation ⛄, we'll figure out if we're going to create a section in an existing topic, add a reference topic, or create a tutorial. I'll discuss it with management, and we'll see what's best.

Leave this issue open. It will close automatically when the PR merges later.

[guardrex]

@LeaFrock ... Ok, I'm just back from the holiday break 🎉.

This node's topics are scheduled for an overhaul and update on #19286, and we could merely focus on the Hosted WASM with sub-path scenario at this time. However, I think the whole presentation for Linux can be addressed as part of this.

Seems like a new section should be added to the Blazor WASM host and deploy article at the H2 level so that it shows up in the doc's ToC sidebar. The section can be titled Hosted deployment on Linux.

The app config for Nginx and Apache should be the same, so app config can be covered first, including your notes on path setup ☝️. Then, there can be two H3 sections, Nginx and Apache. I think both should have config without a sub-path and then have the sub-path scenario config.

WRT the Blazor Server coverage, we didn't organize for sub-path coverage, so that's something that I'd seek to address for this work, too ...

• Blazor Server Nginx config
• Immediately under that section ☝️ ... Blazor Server Apache config

I have a NIT concern about the Blazor Server > Apache section because I can't tell if the _blazor URI segment is a requirement or not without a sub-path. I wouldn't think it would be required in a non-sub-path scenario. However, that config was supplied by one of the MS engineers: They either have the correct non-sub-path config or they felt that Apache folks will recognize that the example is a sub-path config. Anyway, that's a side-NIT on my part not knowing more about Apache config. I'll ping for help on that ... or perhaps you've seen or worked with Apache config and can advise on it.

Two more notes ...

1. WRT location /blazor ..., using blazor as the path segment: I'll use a placeholder there, such as location /{PATH} ...).
2. I think the server config examples should be complete. Devs seem to favor fully-working, cut-'n-paste examples.

I'll take a shot at setting this up on a PR this morning, and I'll ping you on the PR for review + remarks.

[guardrex]

😆 ... Nevermind! I misunderstood the example for a sec. I see now that you're saying that /blazor isn't required when the HttpClient service extension is called. Sorry about that.

Ok ... I'll keep working the content forward for the PR and ping u ...... 🤔 ... probably tomorrow (Friday). I'll probably sleep on this one! 🛏️😴 lol

[guardrex]

It's very DRAFT at the moment. I'll ping you tomorrow from the PR when it's a bit further along ... and I definitely need to do some further research on the Apache proxy configuration.

[guardrex]

@BrennanConroy ... TL;DR the earlier parts of this issue, everything is cool thus far with the ask and work on the PR is proceeding well.

Can you assist me with SignalR Linux-Nginx configuration? There are deltas between the Blazor Server host and deploy doc and the SignalR scale doc.

According to the SignalR scale doc, connection upgrade and keep alive in the map section are configured like this ...

map $http_connection $connection_upgrade {
    "~*Upgrade" $http_connection;
    default keep-alive;
}

When we placed the Blazor Server Linux-Nginx guidance into the Blazor Server host and deploy doc several years ago, the part of the config for map came over from the PU (I don't recall which engineer sent it) as ...

For SignalR WebSockets to function properly, confirm that the proxy's Upgrade and Connection headers are set to the following values and that $connection_upgrade is mapped to either:

• The Upgrade header value by default.
• close when the Upgrade header is missing or empty.

... and just showing the map bit here from the full config ...

map $http_upgrade $connection_upgrade {
    default Upgrade;
    ''      close;
}

Should I change that to match what's in the SignalR scale doc for map?

Side Note: I'll be adding proxy_cache off;, proxy_buffering off;, and proxy_read_timeout 100s; to the location section to match the SignalR doc. Otherwise, the configurations are the same.

As an alternative to all of this, I could drop the Blazor Server Linux-Nginx coverage and cross-link to the SignalR doc's section. If I do that tho ...

• Shouldn't I state that in the base config the dev doesn't need to configure the hub endpoint because the SignalR example states location /hubroute { ... }? Shouldn't I tell the reader to just use location / { ... }? If they're using a sub-app path, they'd configure it (e.g., location /blazor { ... } for a Blazor Server app that responds at /blazor).
• We'd be assuming the SignalR scale doc's version of map is the correct config for Blazor Server apps.

I do like the idea 🤔 of cross-linking with just a bit of location guidance. Do you favor that instead of my updating the Blazor Server doc?

Last ❓ ... For Apache, I don't see SignalR config. Is such config anywhere that you know? We're carrying Blazor Server Linux-Apache coverage. This issue pertains primarily to sub-app path hosting scenarios, and I'm going to try and work that out and/or get help with Apache, but I'm also trying to get the base config Apache guidance for non-sub-app path hosting checked/updated.

NEVERMIND last remark on Apache: I see you remarked on that back in 2017. I'll work off that bit the dev supplied sans his rewrite config part ... I'm just interested in the base config for a default scenario. We'll tell readers to hit up the community for advanced/special setups. Cross-ref: aspnet/SignalR#1150 (comment)

UPDATE (1/10) on Apache: Upon further analysis looking at a few different Apache configs on the Net, I'll consult with Artak shortly on proceeding myself with it. Looks like it might be best to get a dev with significant Apache experience to assess the coverage and advise on it.

Thanks for your help.