port docs to mdbook

docs/src/SUMMARY.md

@@ -1,3 +1,23 @@
 # Summary
 
-- [Chapter 1](./chapter_1.md)
+- [Introduction](./introduction.md)
+- [Running]()
+    - [Installation](./running/installation.md)
+    - [Basic configuration](./running/basic-configuration.md)
+- [Configuring]()
+    - [Cache](./configuring/cache.md)
+    - [Captcha](./configuring/captcha.md)
+    - [Database](./configuring/database.md)
+    - [Emailing](./configuring/email.md)
+    - [Federation filter](./configuring/federation-filter.md)
+    - [Instance](./configuring/instance.md)
+    - [Job Scheduler](./configuring/job-scheduler.md)
+    - [Link embedding](./configuring/link-embedding.md)
+    - [Messaging](./configuring/messaging.md)
+    - [OIDC (OpenID Connect)](./configuring/oidc.md)
+    - [OpenTelemetry](./configuring/opentelemetry.md)
+    - [Search](./configuring/search.md)
+    - [Storage](./configuring/storage.md)
+- [Specification]()
+    - [HTTP signatures](./spec/http-signatures.md)
+    - [Webfinger](./spec/webfinger.md)

docs/src/configuring/cache.md

@@ -0,0 +1,36 @@
+# Cache
+
+Computing things from scratch can be pretty expensive, that's where caching comes in.  
+To best fit for your specific setup, Kitsune has multiple caching backends:
+
+## No Cache
+
+```toml
+[cache]
+type = "none"
+```
+
+This is the simplest of all caching modes. It just doesn't cache anything at all and utilises Kitsune's no-op cache. 
+Pretty much only desirable if you are debugging other caches for invalidation issues (or if you have *heavy* memory constraints and no way to get your hands on a Redis instance).
+
+**Note**: This setting is incompatible with the OIDC feature since the OIDC service uses a cache type under the hood to keep track of login states.
+
+## In-Memory Cache
+
+```toml
+[cache]
+type = "in-memory"
+```
+
+This tells Kitsune to cache data directly into its memory. The cache is bounded so it doesn't make you run out of memory.
+
+## Redis Cache
+
+```toml
+[cache]
+type = "redis"
+redis-url = "redis://[Your Redis instance]"
+```
+
+This tells Kitsune to cache data via expiring keys into the configured Redis instance.  
+This is the optimal configuration for setups where you have multiple Kitsune nodes running at the same time.

docs/src/configuring/captcha.md

@@ -0,0 +1,35 @@
+# Captcha
+
+Kitsune offers the ability to require captchas on sign-up to protect your service against spam waves.
+
+We offer different implementations to fit your specific needs
+
+## hCaptcha
+
+The rather well-known [hCaptcha service](https://www.hcaptcha.com/) advertises itself as a more privacy-oriented alternative to Google's reCaptcha.
+
+To use it to protect your instance, add the following to your configuration:
+
+```toml
+[captcha]
+type = "hcaptcha"
+verify-url = "[Verify URL]"
+site-key = "[Your site key]"
+secret-key = "[Your secret key]"
+```
+
+## mCaptcha
+
+[mCaptcha](https://mcaptcha.org/) is a lesser known open-source self-hostable captcha service.  
+Technically it isn't a "captcha" and more of a "proof-of-work verification system", but it should defend your service against large spam attacks.
+
+To use mCaptcha, add the following to your configuration:
+
+```toml
+[captcha]
+type = "mcaptcha"
+widget-link = "[Widget link]"
+site-key = "[Your site key]"
+secret-key = "[Your secret key]"
+verify-url = "[Verify URL]"
+```

docs/src/configuring/database.md

@@ -0,0 +1,25 @@
+# Database
+
+Kitsune requires a PostgreSQL installation that it can connect to since we make usage of Postgres-specific features, such as their full-text search.
+
+You can find instructions on creating a database (along with password-protected user) [here](https://medium.com/coding-blocks/creating-user-database-and-adding-access-on-postgresql-8bfcd2f4a91e).
+
+> We supported SQLite in the past (before v0.0.1-pre.1), but the support has been dropped due to a high maintenance burden and rather little expected usage.
+
+## Database URL structure
+
+```
+postgres://[Username]:[Password]@[DBMS host]:[Port]/[Database name]
+```
+### Example URL
+
+```
+postgres://database-user:password-here@localhost:5432/db-name-here
+```
+
+## Maximum connections
+
+The `max-connections` setting defines how many connections the globally shared connection pool will open to the database server *at maximum*.  
+What you should set this value to depends on many factors.
+
+> We currently do not report any pool metrics via the Prometheus endpoint. This might be added in the future.

docs/src/configuring/email.md

@@ -0,0 +1,49 @@
+# Emailing
+
+Configuring an Email server for Kitsune automatically enables account confirmation via Email.
+
+The mailer currently only supports SMTP, no provider-specific REST APIs.
+
+## Example
+
+```toml
+[email]
+from-address = "[email protected]"
+host = "your.smtp.host"
+username = "admin"
+password = "password"
+starttls = false
+```
+
+There is also an option config you can place in front of "from_address" if your email service provider does not do TLS over 465 and instead uses 587 (STARTTLS).
+
+Here is an example configuration utilizing STARTTLS:
+
+```toml
+[email]
+from_address = "[email protected]"
+host = "your.smtp-host.example"
+username = "admin"
+password = "password"
+starttls = true
+```
+
+## Parameters
+
+```starttls``` :
+
+By default Kitsune users the port 465 to send mail. 
+
+Most service providers use this port, but some (for example Postmark) need to have their TLS usage bootstrapped via STARTTLS over port 587. 
+
+```from-address``` :
+
+This is the address Kitsune puts into the `From` field of the Email
+
+```host``` : 
+
+This is the domain that your SMTP server is reachable under.
+
+```username, password``` :
+
+The credentials to your SMTP server. Which values to put here vary from provider to provider.

docs/src/configuring/federation-filter.md

@@ -0,0 +1,33 @@
+# Federation filter
+
+Kitsune has a basic federation filter. It has two main modes of operation:
+
+- Allowlist-based
+- Denylist-based
+
+The domain list supports [globbing](https://en.wikipedia.org/wiki/Glob_(programming)), so can, among other things, define wildcard blocks.
+
+## Allowlist
+
+As the name might suggests, this mode allows instance administrators to define a set list of domains the server is allowed to interact with.  
+Federation attempts from any other server are rejected.
+
+### Configuration example
+
+```toml
+[instance.federation-filter]
+type = "allow" 
+domains = ["*.myfriends.com", "cool-instan.ce"]
+```
+
+## Denylist
+
+This is the opposite of the allowlist-based federation. In this mode, Kitsune generally accepts federation attempts from any instance *except* the ones defined in the domain list.
+
+### Configuration example
+
+```toml
+[instance.federation-filter]
+type = "deny"
+domains = ["*.badstuff.com", "mean-people.biz"]
+```

docs/src/configuring/instance.md

@@ -0,0 +1,40 @@
+# Instance
+
+Kitsune has a number of configurations that change how your instance works.
+
+```toml
+[instance]
+name = "Kitsune"
+description = "https://www.youtube.com/watch?v=6lnnPnr_0SU"
+character-limit = 5000
+registrations-open = true
+```
+
+## `name`
+
+This changes the name of the instance displayed on the landing page and returned via instance metadata endpoints (such as Mastodon's `/api/v1/instance`).
+
+## `description`
+
+Similar to `name`, this setting adjusts the description on the landing page and the one returned via the metadata endpoints.
+
+> **Note**: This field is interpreted as raw HTML
+
+## `character-limit`
+
+This setting sets the character limit specific to your instance.
+
+## `registrations-open`
+
+Determines whether your instance accepts new users or not. When set to `false`, the registration APIs will return a failure code.
+
+## `webfinger-domain`
+
+This enables you to host your `.well-known/webfinger` resource on your main domain (i.e. `example.com`) and the web UI and inboxes on a subdomain (i.e. `kitsune.example.com`).  
+The advantage of this configuration is that your handle can be `@[email protected]`, while the account is hosted on `fedi.example.com`.
+
+### Example value
+
+```toml
+webfinger-domain = "example.com"
+```

docs/src/configuring/job-scheduler.md

@@ -0,0 +1,25 @@
+# Job Scheduler
+
+Kitsune uses the database to store and retrieve jobs that have to be run. 
+There are options to tune the job scheduler to your specific needs.
+
+```toml
+[job-queue]
+redis-url = "redis://localhost"
+num-workers = 20
+```
+
+## `redis-url`
+
+This option configures the Redis instance that the jobs are put on.
+
+We utilize Redis streams and transactional Lua scripting to ensure no jobs are lost even in the case of a crash.
+
+## `job-workers`
+
+This option configures how many jobs are run concurrently at the same time.  
+
+Each job is a lightweight task inside Kitsune's async runtime, so you can raise this well above what you'd raise a thread limit to.
+
+> **Caution**: Each activity delivery is a job, and each of the delivery jobs run multiple connections concurrently. 
+> Raising this job worker limit too high without also increasing the maximum file descriptors might lead to weird issues.

docs/src/configuring/link-embedding.md

@@ -0,0 +1,11 @@
+# Link embedding
+
+Kitsune has the ability to show link previews as so-called "embed cards".  
+We use [Lantern Chat's `embed-service`](https://github.com/Lantern-chat/embed-service/) to provide this functionality.
+
+To use it with Kitsune, run the `embed-service` and add the following configuration to Kitsune's configuration file:
+
+```toml
+[embed]
+service-url = "[URL to the embed service]"
+```

docs/src/configuring/messaging.md

@@ -0,0 +1,26 @@
+# Messaging
+
+Kitsune uses messaging services to exchange events for cache invalidation, notification delivery, etc.  
+To offer flexibility and to make self-hosting as easy as possible, we have multiple such backends.
+
+## Redis backend
+
+This is backend you should choose when running multiple nodes in parallel. This then uses Redis' PubSub feature to exchange messages.
+
+### Configuration example
+
+```toml
+[messaging]
+type = "redis"
+redis-url = "redis://localhost:6379"
+```
+
+## In-process
+
+This backend is optimal for small self-contained installations. It uses Tokio's broadcast channel internally.
+
+### Configuration example
+
+```toml
+[messaging]
+type = "in-process"

docs/src/configuring/oidc.md

@@ -0,0 +1,35 @@
+# OIDC (OpenID Connect)
+
+> This feature is gated behind the `oidc` compile-time feature
+
+OpenID Connect (OIDC) is a technology to provide Single Sign-On (SSO) that it shared across multiple services. 
+This is useful if you, for example, want to run Kitsune together with a bunch of other services and don't want to maintain multiple logins.
+
+In order to enable OIDC for your Kitsune instance, find the `oidc` parameter inside the `server` configuration section. 
+Set this parameter to the following value:
+
+```toml
+[server.oidc]
+server-url = "[Issuer URL]"
+client-id = "[Kitsune's Client ID]"
+client-secret = "[Kitsune's Client Secret]"
+```
+
+## Server URL
+
+This is the URL of the issuer; this setting differs between OIDC solutions. Don't worry, Kitsune won't start up if this value is invalid.
+
+## Client ID and Secret
+
+These values are created on the dashboard of the OIDC solution you are using. 
+Kitsune needs these to obtain an access token from the OIDC server to do introspection and obtain some information about the user.
+
+## Kitsune-specific OIDC requirements
+
+The OIDC server **must** return the following values in the claim:
+
+- `preferred_username`
+- `email`
+
+> Keep the preferred username field unique. The username is used to identify the user inside Kitsune's database that's getting registered.  
+> This might change in the future.

docs/src/configuring/opentelemetry.md

@@ -0,0 +1,14 @@
+# OpenTelemetry
+
+Kitsune can export its traces and metrics via the OpenTelemetry Protocol (or OTLP, for short).  
+
+To push the data to an endpoint, add the following to your configuration:
+
+```toml
+[opentelemetry]
+http-endpoint = "[URL of your HTTP endpoint]"
+```
+
+This pushes both, metrics and traces, to the same endpoint
+
+> Note: We might change this in the future and allow to push metrics and traces to separate endpoints