deployment and host config documentation

Author: pimbrouwers

documentation/authentication.md

@@ -76,4 +76,4 @@ let logOut : HttpHandler =
     Response.signOutAndRedirect authScheme redirectTo
 ```
 
-[Next: Example - Hello World](example-hello-world.md)
+[Next: Deployment](deployment.md)

documentation/deployment.md

@@ -0,0 +1,44 @@
+# Deployment
+
+One of the key features of Falco is that it contains little to no "magic" (i.e., no hidden reflection or dynamic code). This means that Falco is both [trimmable](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/trim-self-contained) and [AOT](https://learn.microsoft.com/en-us/dotnet/core/deploying/native-aot) compatible out of the box.
+
+This means that you can deploy your Falco application as a self-contained executable, or as a native AOT executable, with no additional configuration. A huge benefit of this is that you can deploy your Falco application to any environment, without having to worry about the underlying runtime or dependencies.
+
+> Important! If you're in a __scale-to-zero__ hosting environment consider using a [ReadyToRun](https://learn.microsoft.com/en-us/dotnet/core/deploying/ready-to-run) deployment. This will ensure that your application will experience faster cold start times.
+
+## Self-contained deployments
+
+It is highly recommended to deploy your Falco application as a self-contained executable. This means that the .NET runtime and all dependencies are included in the deployment package, so you don't have to worry about the target environment having the correct version of .NET installed. This will result in a slightly larger deployment package, but it will ensure that your application runs correctly in any environment. The larger binary size can also be offset by using trim.
+
+Below is an example [Directory.Build.props] that will help enable the non-AOT features. These properties can also be added to you fsproj file.
+
+```xml
+<Project>
+    <PropertyGroup>
+        <SelfContained>true</SelfContained>
+        <PublishSingleFile>true</PublishSingleFile>
+        <PublishTrimmed>true</PublishTrimmed>
+        <TrimMode>Link</TrimMode>
+        <IncludeNativeLibrariesForSelfExtract>true</IncludeNativeLibrariesForSelfExtract>
+        <EnableCompressionInSingleFile>true</EnableCompressionInSingleFile>
+        <!-- Optional: enable if in scale-to-zero hosting environment -->
+        <!-- <PublishReadyToRun>true</PublishReadyToRun> -->
+    </PropertyGroup>
+</Project>
+```
+
+## Native AOT deployments
+
+Publishing your app as Native AOT produces an app that's self-contained and that has been ahead-of-time (AOT) compiled to native code. Native AOT apps have faster startup time and smaller memory footprints. These apps can run on machines that don't have the .NET runtime installed.
+
+Since AOT deployments require trimming, and are single file by nature the only required msbuild property is:
+
+```xml
+<Project>
+    <PropertyGroup>
+        <PublishAot>true</PublishAot>
+    </PropertyGroup>
+</Project>
+```
+
+[Next: Example - Hello World](example-hello-world.md)

documentation/get-started.md

@@ -50,7 +50,8 @@ let wapp = WebApplication.Create()
 wapp.UseRouting()
     .UseFalco(endpoints)
     // ^-- activate Falco endpoint source
-    .Run()
+    .Run(Response.ofPlainText "Not found")
+    // ^-- run app and register terminal (i.e., not found) middleware
 ```
 
 Run the application:
@@ -61,8 +62,4 @@ Run the application:
 
 And there you have it, an industrial-strength [Hello World](https://github.com/pimbrouwers/Falco/tree/master/examples/HelloWorld) web app. Pretty sweet!
 
-## Sample Applications
-
-Code is worth a thousand words. For the most up-to-date usage, the [examples](https://github.com/pimbrouwers/Falco/tree/master/examples/) directory contains a few sample applications.
-
-[Next: Routing](routing.md)
+[Next: Host Configuration](host-configuration.md)

documentation/host-configuration.md

@@ -0,0 +1,66 @@
+# Host Configuration
+
+As your app becomes more complex, you'll inevitably need to reach for some additional host configuration. This is where `Microsoft.AspNetCore.Builder` comes in, which contains many useful extensions for configuring the server (ex: static files, authentication, authorization etc.).
+
+Most of the extension methods have existed since the early days of ASP.NET Core and operate against `IApplicationBuilder`. But more recent version of ASP.NET Core have introduced a new `WebApplication` type that implements `IApplicationBuilder` and provides some additional functionality, most notably endpoint configuration. This dichotomy makes pipelining next to impossible. In C# you don't feel the sting of this as much because of `void` returns. But in F# this results in an excess amount of `|> ignore` calls.
+
+Let's take the hero code from the [Getting Started](get-started.md) page and add some static file middleware to it:
+
+```fsharp
+module Program
+
+open Falco
+open Falco.Routing
+open Microsoft.AspNetCore.Builder
+
+let wapp = WebApplication.Create()
+
+wapp.UseRouting()
+    .UseDefaultFiles() // you might innocently think this is fine
+    .UseStaticFiles()  // and so is this
+                       // but uknowingly, the underlying type has changed
+    .UseFalco([
+        get "/" (Response.ofPlainText "Hello World!")
+    ])
+    .Run(Response.ofPlainText "Not found")
+    // ^-- this is no longer starts up our application
+
+// one way to fix this:
+wapp.UseRouting() |> ignore
+wapp.UseDefaultFiles().UseStaticFiles() |> ignore
+
+wapp.UseFalco([
+        get "/" (Response.ofPlainText "Hello World!")
+    ])
+    .Run(Response.ofPlainText "Not found")
+
+// but we can do better
+```
+
+To salve this, Falco comes with a several shims. The most important of these are `WebApplication.Use` and `WebApplication.UseIf` which allow you to compose a pipeline entirely driven by `WebApplication` while at the same time taking advantage of the existing ASP.NET Core extensions.
+
+The optional, but recommended way to take advantage of these is to utilize the static methods that server as the underpinning to the various extension methods available. The code below will attempt to highlight this more clearly:
+
+```fsharp
+// consider
+wapp.UseRouting()
+    .Use(fun (appl : IApplicationBuilder) ->
+        appl.UseDefaultFiles()
+            .UseStaticFiles())
+    .UseFalco([
+        get "/" (Response.ofPlainText "Hello World!")
+    ])
+    .Run(Response.ofPlainText "Not found")
+
+// or better yet
+wapp.UseRouting()
+    .Use(DefaultFilesExtensions.UseDefaultFiles)
+    .Use(StaticFileExtensions.UseStaticFiles)
+      // ^-- most IApplicationBuilder extensions are available as static methods similar to this
+    .UseFalco([
+        get "/" (Response.ofPlainText "Hello World!")
+    ])
+    .Run(Response.ofPlainText "Not found")
+```
+
+[Next: Routing](routing.md)

documentation/readme.md

@@ -1,19 +1,17 @@
----
-title: Welcome to Falco's documentation
----
+# Welcome to Falco's Documentation
 
-# Documentation
-
-Welcome to Falco's documentation, visit the [getting started](get-started.md) page for installation and a brief overview. There are also more detailed [examples](example-hello-world.md) that shows how to create a small but complete application with Falco. The rest of the docs describe each component of Falco in detail.
+Visit the [getting started](get-started.md) page for installation and a brief overview. There are also more detailed [examples](example-hello-world.md) that shows how to create a small but complete application with Falco. The rest of the docs describe each component of Falco in detail.
 
 ## Guides
 
 Falco depends only on the high-performance base components of .NET and ASP.NET Core, and provides a toolset to build a working full-stack web application. This section of the documentation explains the different parts of Falco and how they can be used, customized, and extended. Beyond Falco itself, look for community-maintained extensions to add even more functionality.
 
 - [Getting Started](get-started.md)
+- [Host Configuration](host-configuration.md)
 - [Routing](routing.md)
 - [Writing responses](response.md)
 - [Accessing request data](request.md)
 - [View engine](markup.md)
 - [Security](authentication.md)
+- [Deployment](deployment.md)
 - [Examples](example-hello-world.md)