Including a Single-Page App (SPA) in an ASP.NET Core Docker Container

November 9, 2024

asp.net core docker single-page app

This is a continuation of how to Serve a Single Page App (SPA) With ASP.NET Core. In that post, I explain how you can build your SPA and include the build artifacts when you run an ASP.NET Core app.

When it comes to deployment, if my backend is 100% in .NET, I would much rather skip deploying another container to run the UI. As described in my post, you can just include the static files from your SPA and ASP.NET Core will include them in its routing.

Additionally, my recent project was split into separate repos: one for the .NET backend and one for the UI – each having their own build and release pipelines.

UI build artifacts

My UI is in React + Vite and its release pipeline is very simple. On a release (any tag prefixed in the format of v*.*.*), it runs npm run build to generate the build artifacts. It then zips the files and uploads the zip to the releases page so that each release has its own package: dist.zip.

  - name: Zip build assets
    run: |
      cd dist
      zip -r ../dist.zip *      

  - name: Publish a release
    uses: softprops/action-gh-release@v2.0.9
    if: startsWith(github.ref, 'refs/tags/')
    with:
      files: dist.zip

Building the ASP.NET Core backend container

Say you have the standard image that builds and runs your ASP.NET Core app:

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
USER $APP_UID
WORKDIR /app
EXPOSE 5000

# .NET Build stage
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
# Dependencies
COPY ["src/Apps/MlbTheShowForecaster.Apps.Gateway/MlbTheShowForecaster.Apps.Gateway.csproj", "."]
RUN dotnet restore "MlbTheShowForecaster.Apps.Gateway.csproj"
# Source code for building
COPY src/Apps/MlbTheShowForecaster.Apps.Gateway .

# Build
RUN dotnet build "MlbTheShowForecaster.Apps.Gateway.csproj" -c $BUILD_CONFIGURATION -o /app/build

# .NET Publish stage
FROM build AS publish
ARG BUILD_CONFIGURATION=Release
RUN dotnet publish "MlbTheShowForecaster.Apps.Gateway.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false

# Final stage
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .

ENTRYPOINT ["dotnet", "MlbTheShowForecaster.Apps.Gateway.dll"]

Your goal is to now include the UI build artifacts in the final stage. You can accomplish this using a lightweight image like alpine and doing the following:

Getting the release details from the GitHub API
Download and unzip the release’s build artifacts
Copy the build artifacts to the final stage

To do this, you will need curl to request the release, jq to parse the release details, and unzip.

# SPA asset stage - retrieves the required files to run the SPA
FROM alpine AS spa-assets
RUN apk add --no-cache curl unzip jq

The docker build command should be passed a RELEASE_TAG argument, that corresponds to the UI’s release tag.

ARG REPO_OWNER=bretten
ARG REPO_NAME=mlb-the-show-forecaster-ui
ARG RELEASE_TAG
RUN echo "Using UI SPA release $RELEASE_TAG" # Invalidates Docker stage cache if the release tag changes
RUN if [ -z "$RELEASE_TAG" ]; then \
        echo "No release tag specified" >&2; \
        exit 1; \
    else \
        # Get the specific release
        curl -s "https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/releases/tags/${RELEASE_TAG}" \
            -o release.json; \
    fi

The release.json file contains the response from the releases request. The part we are interested in is the assets array that lists all the files attached to the release. This will include the dist.zip from the UI repo’s release pipeline.

{
   "assets": [
      {
         "url": "url",
         "id": 1,
         "node_id": "",
         "name": "dist.zip",
         "label": ""
      }
   ]
}

You need to parse out the id of the asset so that you can make a request to download it. The line below will look for the asset named dist.zip, parse out its id, and finally download and unzip it.

# Parse the release ID from the Github API response and use it to download the zip containing the SPA files
RUN mkdir -p /assets && \
    asset_id=$(jq -r '.assets[] | select(.name=="dist.zip") | .id' release.json) && \
    if [ -z "$asset_id" ] || [ "$asset_id" = "null" ]; then \
        echo "No dist.zip found" >&2; \
        exit 1; \
    fi && \
    echo "Asset ID: $asset_id" && \
    curl -L  -H "Accept: application/octet-stream" "https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/releases/assets/${asset_id}" -o /assets/dist.zip && \
    ls -l /assets/dist.zip && \
    unzip /assets/dist.zip -d /assets && \
    rm /assets/dist.zip && rm release.json

Now that you have the assets, you can copy them from this stage to the final stage:

# Final stage
FROM base AS final
WORKDIR /app
# Copy the ASP.NET Core App
COPY --from=publish /app/publish .
# Copy the SPA build artifacts
COPY --from=spa-assets /assets ./wwwroot

Now, when you run the ASP.NET Core container (that has been configured for an SPA), it will include the static build files in the app’s routing.

Gotchas

Docker may cache the stage that downloads the dist.zip asset unless you invalidate it

Since Docker invalidates the cache anytime a command changes, you can just make sure to echo whichever RELEASE_TAG is being retrieved. This will make the command change each time the tag is different.

Private repos

If your repository is private, you will need to authenticate against the GitHub API.