Container Documentation (#73)

resolves #46 

* Add documentation on running containers.
* re-enable static file host to allow serving OpenAPI files
* Add build argument to Dockerfile to specify whether to copy the OpenAPI specs
* fix build warning when wwwroot does not exist
* include swagger-ui HTML files in OPENAPI builds
* copy SwaggerUI into container

docs/containers.md

@@ -0,0 +1,64 @@
+# Running in a container
+
+It is possible to self-host the API by either running it directly or by running it as a container.
+This allows you to access the API in secured networks (although you'll still need to
+be able to access the ArrowHead API endpoints of course), or to run an instance
+with modified settings (such as rate limits).
+
+### Building the container
+First make sure you have cloned the repository:
+```shell
+git clone --recurse-submodules https://github.com/helldivers-2/api.git
+```
+
+Then build the container so it's ready for local use (run this *inside* the cloned folder):
+```shell
+docker build -f ./src/Helldivers-2-API/Dockerfile -t helldivers2-api .
+```
+
+and finally run the image:
+```shell
+docker run -p 8080:8080 helldivers2-api
+```
+
+### Building the container with OpenAPI
+By default the OpenAPI specifications aren't bundled in the container image,
+you can enable OpenAPI support by building the container with these flags:
+```shell
+docker build --build-arg="OPENAPI=true" -f ./src/Helldivers-2-API/Dockerfile -t helldivers2-api .
+```
+
+### Customizing the runtime of the API
+Other settings, such as rate limits, features, ... can be customized at runtime
+and don't need to be defined at build time of the container.
+
+For a **full** list of options that can be customized, please inspect
+[appsettings.json](https://github.com/helldivers-2/api/blob/master/src/Helldivers-2-API/appsettings.json) as all these settings can be overriden.
+
+For example, the `appsettings.json` configuration contains a key like this:
+```json
+{
+  // omitted for brevity
+  "Helldivers": {
+    "Synchronization": {
+      "IntervalSeconds": 20,
+      // omitted for brevity
+  }
+}
+```
+The `IntervalSeconds` defines the rate at which the API will synchronize with ArrowHead's
+API endpoints, in this example it will synchronize every `20` seconds.
+Let's say we want to update this in our own container to run every `10` seconds instead.
+
+We can do this by defining an environment variable that overrides the configuration defined
+in `appsettings.json`.
+in this case the property we're overriding is set under
+`Helldivers:Synchronization:IntervalSeconds`, so we need to declare a variable called
+`Helldivers__Synchronization__IntervalSeconds` with value `10`
+
+You can define environment variables for your container like this:
+```shell
+docker run -p 8080:8080 -e "Helldivers__Synchronization__IntervalSeconds=10" helldivers2-api
+```
+
+You can read more about using environment variables to override configuration [here](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-8.0#naming-of-environment-variables)

docs/toc.yml

@@ -2,8 +2,8 @@
   href: introduction.md
 - name: Getting Started
   href: getting-started.md
-- name: SwaggerUI
-  href: ./openapi/swagger-ui.html
+- name: Containers
+  href: containers.md
 - name: Contributing
   href: ../contributing.md
 - name: Code of conduct

src/Helldivers-2-API/Dockerfile

@@ -3,12 +3,14 @@ USER $APP_UID
 WORKDIR /app
 
 FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS build
-RUN apk add --upgrade --no-cache \
-        build-base \
-        clang \
-        zlib-dev
+RUN apk add --upgrade --no-cache build-base clang zlib-dev
 ARG BUILD_CONFIGURATION=Release
 ARG BUILD_RUNTIME=linux-musl-x64
+ARG OPENAPI=false
+
+WORKDIR /
+COPY ./docs/openapi /docs/openapi
+
 WORKDIR /src
 
 COPY ["src/Helldivers-2-API/Helldivers-2-API.csproj", "Helldivers-2-API/"]
@@ -21,6 +23,13 @@ COPY ["Directory.Build.props", "."]
 RUN dotnet restore -r $BUILD_RUNTIME "Helldivers-2-API/Helldivers-2-API.csproj"
 COPY ./src .
 WORKDIR "/src/Helldivers-2-API"
+RUN if [[ "${OPENAPI}" = 'true' ]]; \
+  then \
+    echo "OPENAPI is set to ${OPENAPI}, running OpenAPI generators" \
+    && dotnet build "Helldivers-2-API.csproj" --no-restore -c Debug \
+    && mkdir -p wwwroot \
+    && cp /docs/openapi/* wwwroot/ \
+  ; fi
 RUN dotnet build "Helldivers-2-API.csproj" --no-restore -r $BUILD_RUNTIME -c $BUILD_CONFIGURATION -o /app/build
 
 FROM build AS publish

src/Helldivers-2-API/Program.cs

@@ -145,6 +145,10 @@
 // Use response compression for smaller payload sizes
 app.UseResponseCompression();
 
+// Enable static file host in case the application was built with OpenAPI specifications publicly available (Docker)
+if (Directory.Exists(app.Environment.WebRootPath))
+    app.UseStaticFiles();
+
 // select the correct culture for incoming requests
 app.UseRequestLocalization();
 

toc.yml

@@ -1,4 +1,6 @@
 - name: Docs
   href: docs/
+- name: OpenAPI
+  href: /docs/openapi/swagger-ui.html
 - name: API
   href: api/