How to Host Blazor WASM on Docker

Introduction

So you’ve built a fancy Blazor WebAssembly (WASM) app. Now you want to run it in Docker. Great choice, Docker is a portable way to ship and run your app anywhere.

In this article, I’ll show you how to create, build, and run your Blazor WASM app inside a Docker container using NGINX.

This is Part 4 of our .NET Docker Series. If you haven’t already, check out the earlier parts.

Step 1. Create Your Blazor WASM App.

If you haven’t created a Blazor WebAssembly app yet, you can do so using the .NET CLI.

dotnet new blazorwasm -o DockingBlazor

This creates a Blazor WebAssembly app in a folder named DockingBlazor.

Or, if you prefer using the GUI.

GUI

Image 1. Creating a new Blazor WebAssembly project using Visual Studio

Now let’s Dockerize the project.

Step 2. Where to Add the Docker Files.

In the root folder of your solution (same level as DockingBlazor.sln), add the following two files.

Dockerfile: to define how the container is built
default.conf: Nginx config that helps route requests properly in a Blazor WASM app

Step 3. The Dockerfile.

# Use the .NET 8 SDK image to build the Blazor app
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build

# Set the working directory inside the container
WORKDIR /app

# Copy the solution file into the container
COPY DockingBlazor.sln ./

# Copy the project file into the container (needed before restore)
COPY DockingBlazor/DockingBlazor.csproj ./DockingBlazor/

# Restore NuGet packages (uses Docker layer caching effectively)
RUN dotnet restore

# Copy the rest of the source code into the container
COPY . ./

# Publish the app in Release mode to the 'out' folder
RUN dotnet publish -c Release -o out

# Use the Nginx base image to serve the published app
FROM nginx

# Set a working directory (optional, for consistency)
WORKDIR /app

# Expose port 80 (the default port Nginx listens on)
EXPOSE 80

# Copy the custom Nginx configuration file into the container
COPY default.conf /etc/nginx/conf.d/default.conf

# Copy the published Blazor files to the Nginx web root
COPY --from=build /app/out/wwwroot /usr/share/nginx/html

Step 4. The Nginx Config (default.conf)

# Define a server block
server {

    # Listen on port 80 (inside the container)
    listen 80;

    # Set the server name (not critical for container usage)
    server_name localhost;

    # Set the root directory where Nginx will serve files from
    root /usr/share/nginx/html;

    # Set the default file to serve
    index index.html;

    # Handle requests to the root path or any route
    location / {
        # Try to serve the file directly, or fall back to index.html
        # This is important for Blazor routing to work correctly
        try_files $uri $uri/ /index.html;
    }

    # Match and serve static files with caching
    location ~* \.(js|css|woff2?|eot|ttf|otf|svg|ico|jpg|jpeg|png|gif|webp|wasm)$ {
        # Cache static assets for 30 days to improve performance
        expires 30d;

        # Disable logging access to these files
        access_log off;
    }
}

Step 5. Build and Run the Docker Container.

Open your terminal in the root folder and run.

docker build -t docking-blazor-image .

This builds the Docker image with the tag docking-blazor-image. You'll see it show up under the Images tab in Docker Desktop after this runs.

Docker image

Image 2. Docker image docking-blazor-image appears under the Images tab in Docker Desktop

Now, let’s run the container.

docker run --name docking-blazor-container -d -p 8080:80 docking-blazor-image

This runs your container and maps host port 8080 to container port 80.

Container

Image 3. Docker container docking-blazor-container shows up under Containers in Docker Desktop

you can browse your app at,

http://localhost:8080

You should be able to see your app running like this through the container.

Run

Image 4. Blazor WASM app running in the browser via Docker container

Common Issue: UTF-8 with BOM

If your container fails to start even though everything looks correct, the issue might be your default.conf file's encoding.

Problem: The file might be saved as UTF-8 with BOM (Byte Order Mark), which NGINX doesn’t like.
Solution: Re-save the file using plain UTF-8 (without BOM).

New

Image 5. Changing file encoding from "UTF-8 with BOM" to "UTF-8" in your code editor

Conclusion

That’s it, you’ve officially Dockerized your Blazor WASM app and served it with Nginx!

The next steps could be,

Adding HTTPS with a self-signed or Let's Encrypt certificate
Deploying to Azure, AWS, or another cloud provider
Adding CI/CD pipelines to auto-build and deploy