From 445c91854a3cb49b8c2302cee95125f174b58ce9 Mon Sep 17 00:00:00 2001
From: juliangiebel <juliangiebel@live.de>
Date: Wed, 24 Apr 2024 22:57:31 +0200
Subject: [PATCH] Finish writing configuration reference

---
 .../topics/Basic-Example-Configuration.md     | 70 +++++++++++++++---
 docs/Writerside/topics/Git-Configuration.md   | 14 ++--
 .../Writerside/topics/Github-Configuration.md | 19 ++++-
 .../topics/Processing-Configuration.md        | 29 ++++++--
 docs/Writerside/topics/Quickstart.md          |  9 ++-
 .../Writerside/topics/Server-Configuration.md | 73 +++++++++++++++++--
 6 files changed, 180 insertions(+), 34 deletions(-)

diff --git a/docs/Writerside/topics/Basic-Example-Configuration.md b/docs/Writerside/topics/Basic-Example-Configuration.md
index f390c83..326f337 100644
--- a/docs/Writerside/topics/Basic-Example-Configuration.md
+++ b/docs/Writerside/topics/Basic-Example-Configuration.md
@@ -1,22 +1,70 @@
 # Basic Example Configuration
 
 ````yaml
+Serilog:
+  Using: [ "Serilog.Sinks.Console" ]
+  MinimumLevel:
+    Default: "Information"
+    Override:
+      SS14: "Information"
+      Microsoft: "Warning"
+      Microsoft.Hosting.Lifetime: "Information"
+      Microsoft.AspNetCore: "Warning"
+      #This service doesn't use data protection
+      Microsoft.AspNetCore.DataProtection: "Error"
+      #Ignore api key spam
+      SS14.MapServer.Security.ApiKeyHandler: "Error" 
+
+  WriteTo:
+    - Name: Console
+      Args:
+        OutputTemplate: "[{Timestamp:HH:mm:ss} {Level:u3} {SourceContext}] {Message:lj}{NewLine}{Exception}"
+
+  Enrich: [ "FromLogContext" ]
+
+AllowedHosts: "*"
+
 Auth:
-    ApiKey: "debug"
+  ApiKey: "<api key>"
 
-Processing:
-    TargetDirectory: "/tmp/mapstest/build"
-    DirectoryPoolMaxSize: 3
+Git:
+  RepositoryUrl: "<repository url>"
+  Branch: "master"
+  # Exclude maps that generally break the map renderer,
+  # like planet maps or you just don't want rendered
+  mapFileExcludePatterns:
+    - "europa.yml"
 
 Github:
-    AppName: "SS14.MapServer"
-    TemplateLocation: "Resources/Templates"
+  AppName: "<github app name>"
+  AppId: <app id>
+  AppPrivateKeyLocation: "private-key.pem"
+  AppWebhookSecret: "<secret>"
+
+ConnectionStrings:
+  default: "Server=map_database;Port=5432;Database=postgres;User Id=postgres;Password=<password>;"
 
 Server:
-    CorsOrigins:
-        - "http://localhost:5173"
-    Language: "en-US"
+  CorsOrigins:
+    - "<map server host>"
+    - "127.0.0.1"
+  Host: "<host>"
+  EnableSentry: true
+  EnableSentryTracing: true
 
-Git:
-    Branch: "master"
+# The sentry integration is entirely optional
+Sentry:
+  Dsn: "<sentry dsn>"
+  EnableTracing: true
+  MaxRequestBodySize: "Always"
+  ServerName: "Live server"
+  # Ensure to keep this too false to prevent GDPR issues
+  SendDefaultPii: false 
+  MinimumBreadcrumbLevel: "Warning"
+  MinimumEventLevel: "Error"
+  AttachStackTrace: true
+  DiagnosticsLevel: "Error"
+
+Build:
+  MapRendererCommand: "Content.MapRenderer"
 ````
\ No newline at end of file
diff --git a/docs/Writerside/topics/Git-Configuration.md b/docs/Writerside/topics/Git-Configuration.md
index 1ba12d4..da10444 100644
--- a/docs/Writerside/topics/Git-Configuration.md
+++ b/docs/Writerside/topics/Git-Configuration.md
@@ -1,6 +1,6 @@
 # Git Configuration
 
-This section contains all of the settings related to working with the content git repository.
+This section contains all the settings related to working with the content git repository.
 
 > Be carefull when changing configuration settings in this section as some are relevant for the servers security
 {style="note"}
@@ -10,10 +10,10 @@ yaml:
   [[[RepositoryUrl|#repositoryurl]]]: <string>
   [[[Branch|#branch]]]: <string>
   [[[RetrieveMapFilesFromDiff|#retrievemapfilesfromdiff]]]: [true|false]
-  [[[MapFilePatterns|#mapfilepatterns]]]: <string>[]
-  [[[MapFileExcludePatterns|#mapfileexcludepatterns]]]: <string>[]
+  [[[MapFilePatterns|#mapfilepatterns]]]: <string[]>
+  [[[MapFileExcludePatterns|#mapfileexcludepatterns]]]: <string[]>
   [[[DontRunWithCodeChanges|#dontrunwithcodechanges]]]: [true|false]
-  [[[CodeChangePatterns|#codechangepatterns]]]: <string>[]
+  [[[CodeChangePatterns|#codechangepatterns]]]: <string[]>
   [[[RunOnPullRequests|#runonpullrequests]]]: [true|false]
   [[[Identity|#identity]]]:
     Name: <string>
@@ -45,12 +45,12 @@ If this is false all maps will get updated on every push.
 > {style="note"}
 
 ### MapFilePatterns
-`<string>[] default="master"`
+`<string[]> default="master"`
 
 Glob patterns of map files to check for.
 
 ### MapFileExcludePatterns
-`<string>[]`
+`<string[]>`
 
 Glob patterns for excluding specific map files.
 
@@ -69,7 +69,7 @@ Prevent updating maps when there where any c# files changed.
 > {style="warning"}
 
 ### CodeChangePatterns
-`<string>[] default=["**/*.cs"]`
+`<string[]> default=["**/*.cs"]`
 
 Glob patterns used for detecting code changed.
 
diff --git a/docs/Writerside/topics/Github-Configuration.md b/docs/Writerside/topics/Github-Configuration.md
index 5b4677a..42c874b 100644
--- a/docs/Writerside/topics/Github-Configuration.md
+++ b/docs/Writerside/topics/Github-Configuration.md
@@ -1,30 +1,43 @@
-# Github Configuration
+# GitHub Configuration
 
-Description
+The GitHub configuration section contains settings required to set up integration with GitHub.
 
 ````yaml
 yaml:
   [[[Enabled|#enabled]]]: [true|false]
+  [[[AppName|#appname]]]: <string>
+  [[[AppPrivateKeyLocation|#appprivatekeylocation]]]: <string>
+  [[[AppId|#appid]]]: <int>
+  [[[TemplateLocation|#templatelocation]]]: <string>
 ````
 
 ## Configuration Options
 ### Enabled
 `[true|false] default=true`
 
-description
+Enables GitHub integration. If this is set to false Posting on PRs and checking changed files doesn't work.
+Setting this to disabled requires GitHub Webhooks to be set up if you still want automatic map rendering.
 
 ### AppName
 `<string>`
 
+The name of the GitHub app.
+
 ### AppPrivateKeyLocation
 `<string>`
 
+The path to the private key file created when setting up the GitHubApp-
+
 ### AppId
 `<int>`
 
+The app id of the GitHub app
+
 ### TemplateLocation
 `<string>`
 
+The location of liquid templates used for GitHub PR comments.
+
 <seealso>
     <!--Provide links to related how-to guides, overviews, and tutorials.-->
 </seealso>
\ No newline at end of file
diff --git a/docs/Writerside/topics/Processing-Configuration.md b/docs/Writerside/topics/Processing-Configuration.md
index 3aa0721..3abc930 100644
--- a/docs/Writerside/topics/Processing-Configuration.md
+++ b/docs/Writerside/topics/Processing-Configuration.md
@@ -1,18 +1,37 @@
 # Processing Configuration
 
-Description
+Settings related to processing maps.
 
 ````yaml
 yaml:
-  [[[value|#value]]]: <type>
+  [[[DirectoryPoolMaxSize|#directorypoolmaxsize]]]: <int>
+  [[[TargetDirectory|#targetdirectory]]]: <string>
+  [[[ProcessQueueMaxSize|#processqueuemaxsize]]]: <int>
+  [[[JunkFilePatterns|#junkfilepatterns]]]: <string[]>
 ````
 
 ## Configuration Options
-### Value
-`<type> default=<default value>`
+### DirectoryPoolMaxSize
+`<int> default=3`
 
-description
+The maximum size of the process directory pool.
+This means that no more than the given amount of directories will be created
+and it in turn dictates the maximum amount of processes that can run in parallel.
 
+### TargetDirectory
+`<string>`
+
+This is the target directory for creating the process directory pool.
+
+### ProcessQueueMaxSize
+`<int> default=6`
+
+The maximum amount of processes that can be queued up before new process requests will be rejected.
+
+### JunkFilePatterns
+`<string[]>`
+
+Glob patterns for files that should be deleted from build directories when getting cleaned.
 
 <seealso>
     <!--Provide links to related how-to guides, overviews, and tutorials.-->
diff --git a/docs/Writerside/topics/Quickstart.md b/docs/Writerside/topics/Quickstart.md
index 1933ead..fe05468 100644
--- a/docs/Writerside/topics/Quickstart.md
+++ b/docs/Writerside/topics/Quickstart.md
@@ -44,7 +44,8 @@ There is a docker image provided for %project-name%:
 # Example docker compose file
 version: '3.3'
 services:
-  # The ss14 map server container doesn't support https on its own. Please use a reverse proxy
+  # The ss14 map server container doesn't support https on its own. 
+  # Please use a reverse proxy
   ss14mapserver:
     image: ghcr.io/juliangiebel/ss14.mapserver:latest
     volumes:
@@ -54,7 +55,8 @@ services:
       - ./build:/app/build
     ports:
       - 5218:80 # Replace 5218 with the port you need
-    # Disables core dumps to prevent maprenderer crashes from filling up your hard drive with over a gigabyte per dump
+    # Disables core dumps to prevent map renderer crashes from filling
+    # up your hard drive with over a gigabyte per dump
     ulimits:
       core:
         hard: 0
@@ -62,7 +64,8 @@ services:
   map_database:
     image: postgres:latest
     environment:
-      - POSTGRES_PASSWORD=postgres # Replace postgres with a randomly generated password
+      # Replace postgres with a randomly generated password
+      - POSTGRES_PASSWORD=postgres
     volumes:
       - ./data:/var/lib/postgresql/data
       - ./init.sql:/docker-entrypoint-initdb.d/init.sql
diff --git a/docs/Writerside/topics/Server-Configuration.md b/docs/Writerside/topics/Server-Configuration.md
index e7495cc..d580e82 100644
--- a/docs/Writerside/topics/Server-Configuration.md
+++ b/docs/Writerside/topics/Server-Configuration.md
@@ -1,17 +1,80 @@
 # Server Configuration
 
-Description
+
 
 ````yaml
 yaml:
-  [[[value|#value]]]: <type>
+  [[[Host|#host]]]: <string>
+  [[[CorsOrigins|#corsorigins]]]: <string[]>
+  [[[Language|#language]]]: <string>
+  [[[UseHttps|#usehttps]]]: [true|false]
+  [[[UseForwardedHeaders|#useforwardedheaders]]]: [true|false]
+  [[[PathBase|#pathbase]]]: <string>
+  [[[RateLimitCount|#ratelimitcount]]]: <int>
+  [[[RateLimitWindowMinutes|#ratelimitwindowminutes]]]: <long>
+  [[[EnableSentry|#enablesentry]]]: [true|false]
+  [[[EnableSentryTracing|#enablesentrytracing]]]: [true|false]
 ````
 
 ## Configuration Options
-### Value
-`<type> default=<default value>`
+### Host
+`<string> default="https://localhost:7154`
+
+The URL the map server is hosted behind.
+
+### CorsOrigins
+`<string[]>`
+
+A list of allowed cors origins.
+
+### Language
+`<string> default="en-us"`
+
+The locale the map server should use.
+
+### UseHttps
+`[true|false] default=false`
+
+Enables https redirection if true. Set this to false if run behind a reverse proxy.
+
+### UseForwardedHeaders
+`[true|false] default=true`
+
+Enables support for reverse proxy headers like "X-Forwarded-Host" if true. Set this to true if run behind a reverse proxy.
+
+### PathBase
+`<string>`
+
+Sets the request base path used before any routes apply i.e. "/base/api/Maps" with "/base" being the PathBase.
+Set this if run behind a reverse proxy on a sub path and the proxy doesn't strip the path the server is hosted on.
+
+> Add a slash before the path: "/path".
+{style="note"}
+
+### RateLimitCount
+`<int> default = 20`
+
+The amount of requests allowed by per client inside the rate limit window.
+
+### RateLimitWindowMinutes
+`<long> default=1`
+
+The amount of time before the rate limit replenishes.
+%project-name% is using a fixed window rate limiter.
+
+
+### EnableSentry
+`[true|false] default=false`
+
+Whether the Sentry integration is enabled or not.
+
+> Configure sentry using the `Sentry` configuration section and any configuration options provided by Sentry.
+> [https://docs.sentry.io/platforms/dotnet/configuration](https://docs.sentry.io/platforms/dotnet/configuration)
+
+### EnableSentryTracing
+`[true|false] default=false`
 
-description
+Enables sentries performance monitoring on endpoints if Sentry is enabled.
 
 <seealso>
     <!--Provide links to related how-to guides, overviews, and tutorials.-->