Basic Deployment Instructions for Avalonia WASM apps

[woojamon]

Added basic instructions to give a clue on how to deploy the wasm app to somewhere else.

---

Backstory:

While dotnet run is cool, I couldn't find any instructions on how to deploy my avalonia wasm app to get it up and running from the cloud.

For more than two days I tried all possible flag variations of dotnet publish -c Release -o artifact -r linux-x64/browser-wasm/osx-arm64 --self-contained and then trying to execute the myApp.Browser.dll file.

I fought through many battles of libhostpolicy.so: cannot open shared object file: No such file or directory and libhostpolicy.dylib: cannot open shared object file: No such file or directory and then when I finally fought through all that I was able to execute the .dll without errors, but also without effect -- the program just exited.

As it turns out, dotnet publish does not produce any AppBundle or any useful executable, at least that I could find. (I was just trying to deploy the starter wasm app from dotnet new avalonia.xplat.)

So finally I got lucky and found a mention of dotnet-serve (https://github.com/natemcmaster/dotnet-serve) somewhere, and found that I could run my app locally from artifact/AppBundle using dotnet serve -d:artifact/AppBundle, but only if I built the app using dotnet build -c Release -o artifact.

So then I tried to deploy dotnet-serve with my app to Azure Web Apps, but the underlying container wouldn't work with it and wouldn't let me chmod permissions on it so make it executable.

Finally, I signed on to Telegram (https://docs.avaloniaui.net/docs/community) and got a tip from @MikeCodesDotNET that the current WASM samples are most likely deployed to Azure Static Web Apps.

As it turns out, I didn't need dotnet-serve at all, nor did I need to execute some .dll from the build output. I just needed to build (not publish) my app and point a web server to the AppBundle folder to serve it as a static site.

Now finally on the fourth day I can start working on my app, since I now have a pipeline to get an app from local to the cloud.

Maybe I'm just dumb, but I hope no one else has to go through that horrible experience of figuring out how to do this. If I had even the simple clues that I'm adding in this pull request, I could have saved many days of frustration and toil and almost settling for some other framework!

[MikeCodesDotNET]

Thanks for improving the docs for the next person!!

[maxkatz6]

I don't know why you had this issue, but it's wrong to use "dotnet build" for WASM production builds.
"dotnet publish" is the command to build browser app. Where "-c" and "-o" are optional but can be useful.

and then trying to execute the myApp.Browser.dll file.

That's the issue. You don't execute webassembly app. It's a web site. It's need to be served on a static web server. Something like with https://github.com/natemcmaster/dotnet-serve (that's something we should mention in the docs for convenience). It's not suitable for production serving though, only to quickly run published.

All you need is (assuming templates, SDK and dotnet-serve tool are already installed):

mkdir wasmtest
cd wasmtest
dotnet new avalonia.xplat
cd wasmtest.Browser
dotnet publish

## At this point "dotnet" will output something like ` Generated app bundle at E:\wasmtest\wasmtest.Browser\bin\Release\net8.0\browser-wasm\AppBundle\`

cd E:\wasmtest\wasmtest.Browser\bin\Release\net8.0\browser-wasm\AppBundle\
dotnet serve

## Which will output something like Listening on any IP:  http://localhost:62512

That's enough. Now, after you tested published bundle, you can copy AppBundle folder to your static web server of choice. Like Azure or GitHub Pages.

-c is Release by default, when running publish.
-o can be used to override output path (instead of somewhere deep in the bin folder)

[maxkatz6]

The problem with running "dotnet build" is that it's not a publishing semantically. Some optimizations or trimming might be disabled, output folder might contain build information unnecessary for production publishing. Even if it works, better to use more specific commands.

[woojamon]

The problem with running "dotnet build" is that it's not a publishing semantically. Some optimizations or trimming might be disabled, output folder might contain build information unnecessary for production publishing. Even if it works, better to use more specific commands.

I agree, that's why I got so caught up on dotnet publish at first, because I really wanted to use publishing semantics.

In fact, now that I have tried your code I think there may be a bug in dotnet publish when -o is specified.

Will you please try the following code and tell me where you find the AppBundle folder in the output artifact directory?

mkdir wasmtest
cd wasmtest
dotnet new avalonia.xplat
cd wasmtest.Browser
dotnet publish -o artifact

[maxkatz6]

@woojamon Generated app bundle at E:\wasmtest\wasmtest.Browser\bin\Release\net8.0\browser-wasm\AppBundle\.

Seems like somebody opened issue there as well dotnet/runtime#94319

[woojamon]

Thanks for your help and pointing out that message, @maxkatz6 !

I'll update the documentation, but I still think basic deployment instructions are needed. While I see that message and know what to do with AppBundle now, when I'm a newbie to Avalonia and trying to deploy even just the template project for the first time, how am I supposed to know that I need AppBundle, especially if it's not in my -o output directory?

So I'll update the instructions to use publish with a comment about where to find the AppBundle. 👍

[maxkatz6]

@woojamon yeah. I think it would be great if this document mentioned:

1. That you need to use "dotnet publish"
2. Where to find the bundle (pointing that .NET actually outputs directory in the end, as it might be different in the future)
3. That you can use "dotnet serve" as a tool to test production builds after the publish.
4. It would be nice to mention, that "-o" parameter is broken currently, with a link I sent in previous message. That's probably will be fixed in .NET 9 only.

[woojamon]

@maxkatz6 you got it, let me make another commit.

[woojamon]

Done.

[maxkatz6]

Thank you!