Use oranda for our website (#425)

* init oranda structure

* switch to non-workspace mode

* generate changelogs from github releases

* port docs to mdbook

* fix opentelemetry docs

* add clacks overhead docs

* fix oidc config

* add other repository

.github/workflows/web.yml

@@ -0,0 +1,99 @@
+# Workflow to build your docs with oranda (and mdbook)
+# and deploy them to Github Pages
+name: Web
+
+# We're going to push to the gh-pages branch, so we need that permission
+permissions:
+  contents: write
+
+# What situations do we want to build docs in?
+# All of these work independently and can be removed / commented out
+# if you don't want oranda/mdbook running in that situation
+on:
+  # Check that a PR didn't break docs!
+  #
+  # Note that the "Deploy to Github Pages" step won't run in this mode,
+  # so this won't have any side-effects. But it will tell you if a PR
+  # completely broke oranda/mdbook. Sadly we don't provide previews (yet)!
+  pull_request:
+
+  # Whenever something gets pushed to main, update the docs!
+  # This is great for getting docs changes live without cutting a full release.
+  #
+  # Note that if you're using cargo-dist, this will "race" the Release workflow
+  # that actually builds the Github Release that oranda tries to read (and
+  # this will almost certainly complete first). As a result you will publish
+  # docs for the latest commit but the oranda landing page won't know about
+  # the latest release. The workflow_run trigger below will properly wait for
+  # cargo-dist, and so this half-published state will only last for ~10 minutes.
+  #
+  # If you only want docs to update with releases, disable this, or change it to
+  # a "release" branch. You can, of course, also manually trigger a workflow run
+  # when you want the docs to update.
+  push:
+    branches:
+      - main
+
+  # Whenever a workflow called "Release" completes, update the docs!
+  #
+  # If you're using cargo-dist, this is recommended, as it will ensure that
+  # oranda always sees the latest release right when it's available. Note
+  # however that Github's UI is wonky when you use workflow_run, and won't
+  # show this workflow as part of any commit. You have to go to the "actions"
+  # tab for your repo to see this one running (the gh-pages deploy will also
+  # only show up there).
+  workflow_run:
+    workflows: [ "Release" ]
+    types:
+      - completed
+
+# Alright, let's do it!
+jobs:
+  web:
+    name: Build and deploy site and docs
+    runs-on: ubuntu-latest
+    steps:
+      # Setup
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: swatinem/rust-cache@v2
+
+      # If you use any mdbook plugins, here's the place to install them!
+
+      # Install and run oranda (and mdbook)
+      # This will write all output to ./public/ (including copying mdbook's output to there)
+      - name: Install and run oranda
+        run: |
+          curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/oranda/releases/latest/download/oranda-installer.sh | sh
+          oranda build
+      
+      - name: Prepare HTML for link checking
+        # untitaker/hyperlink supports no site prefixes, move entire site into
+        # a subfolder
+        run: mkdir /tmp/public/ && cp -R public /tmp/public/oranda
+
+      - name: Check HTML for broken internal links
+        uses: untitaker/[email protected]
+        with:
+          args: /tmp/public/
+
+      # Deploy to our gh-pages branch (creating it if it doesn't exist)
+      # the "public" dir that oranda made above will become the root dir
+      # of this branch.
+      #
+      # Note that once the gh-pages branch exists, you must
+      # go into repo's settings > pages and set "deploy from branch: gh-pages"
+      # the other defaults work fine.
+      - name: Deploy to Github Pages
+        uses: JamesIves/[email protected]
+        # ONLY if we're on main (so no PRs or feature branches allowed!)
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          repository-name: "kitsune-soc/kitsune-soc.github.io"
+          branch: gh-pages
+          # Gotta tell the action where to find oranda's output
+          folder: public
+          token: ${{ secrets.GITHUB_TOKEN }}
+          single-commit: true

.gitignore

@@ -1,3 +1,7 @@
+# Documentation builds
+/dist
+/docs/book
+
 # Rust target directories
 target
 target-analyzer

README.md

@@ -1,7 +1,11 @@
 <div align="center">
 
+<div class="oranda-hide">
+
 # kitsune
 
+</div>
+
 ![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/kitsune-soc/kitsune/rust.yml?style=for-the-badge)
 [![dependency status](https://deps.rs/repo/github/kitsune-soc/kitsune/status.svg?style=for-the-badge)](https://deps.rs/repo/github/kitsune-soc/kitsune)
 

docs/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["aumetra"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Kitsune documentation"

docs/src/SUMMARY.md

@@ -0,0 +1,24 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Running]()
+    - [Installation](./running/installation.md)
+    - [Basic configuration](./running/basic-configuration.md)
+- [Configuring]()
+    - [Cache](./configuring/cache.md)
+    - [Captcha](./configuring/captcha.md)
+    - [Clacks Overhead](./configuring/clacks-overhead.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,34 @@
+# 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).
+
+## 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/clacks-overhead.md

@@ -0,0 +1,24 @@
+# Clacks Overhead
+
+Clacks Overhead is a non-standard HTTP header used for as something like a silent memorial.  
+The header is appended to each response via a middleware.
+
+The header looks something like this:
+
+```
+X-Clacks-Overhead: GNU [Name 1 here], [Name 2 here]
+```
+
+[More info about this header](https://xclacksoverhead.org/home/about)
+
+---
+
+The names for the header can be configured like so:
+
+```toml
+[server]
+clacks-overhead = [
+    "Natalie Nguyen",
+    "John \"Soap\" MacTavish"
+]
+```

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"]
+```