From b724021c4c1a27f5394b8fac387a758f78273e50 Mon Sep 17 00:00:00 2001
From: Lennart <18233294+lennart-k@users.noreply.github.com>
Date: Thu, 17 Apr 2025 21:17:41 +0200
Subject: [PATCH] First attempt at some documentation

---
 .github/workflows/docs.yml | 42 ++++++++++++++++++++++++++
 docs/index.md              | 18 +++++++++++
 docs/installation.md       | 39 ++++++++++++++++++++++++
 docs/rfcs.md               |  3 ++
 docs/setup/oidc.md         | 34 +++++++++++++++++++++
 mkdocs.yml                 | 62 ++++++++++++++++++++++++++++++++++++++
 6 files changed, 198 insertions(+)
 create mode 100644 .github/workflows/docs.yml
 create mode 100644 docs/index.md
 create mode 100644 docs/installation.md
 create mode 100644 docs/rfcs.md
 create mode 100644 docs/setup/oidc.md
 create mode 100644 mkdocs.yml

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..f959d4d
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,42 @@
+name: docs
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - name: Set up build cache
+        uses: actions/cache/restore@v4
+        with:
+          key: mkdocs-material-${{ hashfiles('.cache/**') }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material
+      - run: mkdocs build --clean
+
+      - name: Upload to GitHub Pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4
+
+      - name: Save build cache
+        uses: actions/cache/save@v4
+        with:
+          key: mkdocs-material-${{ hashfiles('.cache/**') }}
+          path: .cache
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000..614b42d
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,18 @@
+# RustiCal
+
+a CalDAV/CardDAV server
+
+!!! warning
+    RustiCal is **not production-ready!**
+    There can be changes to the database without migrations and there's no guarantee that all endpoints are secured yet.
+    If you still want to play around with it in its current state, absolutely feel free to do so but know that not even I use it productively yet.
+
+## Features
+
+- easy to backup, everything saved in one SQLite database
+- [WebDAV Push](https://github.com/bitfireAT/webdav-push/) support, so near-instant synchronisation to DAVx5
+- lightweight (the container image contains only one binary)
+- adequately fast (I'd say blazingly fast™ :fire: if I did the benchmarks to back that claim up)
+- deleted calendars are recoverable
+- Nextcloud login flow (In DAVx5 you can login through the Nextcloud flow and automatically generate an app token)
+- [OpenID Connect](setup/oidc.md) support (with option to disable password login)
diff --git a/docs/installation.md b/docs/installation.md
new file mode 100644
index 0000000..c17b362
--- /dev/null
+++ b/docs/installation.md
@@ -0,0 +1,39 @@
+# Installation
+
+## Manual
+
+```sh
+cargo install --locked --git https://github.com/lennart-k/rustical
+```
+
+## Docker
+
+```sh
+docker run \
+  -p 4000:4000 \
+  -v YOUR_DATA_DIR:/var/lib/rustical/ \
+  -v YOUR_CONFIG_TOML:/etc/rustical/config.toml \
+  -v YOUR_PRINCIPALS_TOML:/etc/rustical/principals.toml \
+  ghcr.io/lennart-k/rustical
+```
+
+## Configuration
+
+### TOML
+
+### Environment variables
+
+The options in `config.toml` can also be configured using environment variables. Names translate the following:
+
+```toml title="config.toml"
+[data_store.toml]
+path = "asd"
+```
+
+becomes `RUSTICAL_DATA_STORE__TOML__PATH`.
+Every variable is
+
+- uppercase
+- prefixed by `RUSTICAL_`
+- Dots become `__`
+- Arrays are JSON-encoded
diff --git a/docs/rfcs.md b/docs/rfcs.md
new file mode 100644
index 0000000..09441c4
--- /dev/null
+++ b/docs/rfcs.md
@@ -0,0 +1,3 @@
+# RFCs
+
+Collection of RFCs relevant to this project
diff --git a/docs/setup/oidc.md b/docs/setup/oidc.md
new file mode 100644
index 0000000..d3d5153
--- /dev/null
+++ b/docs/setup/oidc.md
@@ -0,0 +1,34 @@
+# OpenID Connect
+
+You can set up RustiCal with an OpenID Connect identity provider
+
+## Example: Authelia
+
+```toml title="RustiCal configuration"
+[frontend.oidc]
+name = "Authelia"
+issuer = "https://auth.example.com"
+client_id = "rustical"
+client_secret = "secret..."
+claim_userid = "preferred_username"  # (1)!
+scopes = ["openid", "profile", "groups"]
+require_group = "app/rustical"  # (2)!
+allow_sign_up = false
+```
+
+1. Can be either `preferred_username` or `sub`
+2. Optional: You can require a user to be in a certain group to use RustiCal
+
+```yaml title="Authelia configuration"
+identity_providers:
+  oidc:
+    clients:
+      - client_id: rustical
+        client_secret: secret...
+        public: false
+        consent_mode: implicit
+        scopes: [openid, profile, groups]
+        token_endpoint_auth_method: client_secret_basic
+        redirect_uris:
+          - https://rustical.example.com/frontend/login/oidc/callback
+```
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 0000000..339a514
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,62 @@
+site_name: RustiCal Documentation
+site_url: https://lennart-k.github.io/rustical/
+site_description: a CalDAV/CardDAV server
+
+repo_name: lennart-k/rustical
+repo_url: https://github.com/lennart-k/rustical
+
+theme:
+  name: material
+  palette:
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/link
+        name: Switch to light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/toggle-switch
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: indigo
+      toggle:
+        icon: material/toggle-switch-off
+        name: Switch to system preference
+  font:
+    text: Roboto
+    code: Roboto Mono
+  favicon: assets/favicon.png
+  icon:
+    logo: logo
+  features:
+    - content.code.copy
+    - content.code.annotate
+    - content.tooltips
+    - navigation.indices
+    - navigation.tabs
+
+markdown_extensions:
+  - fenced_code
+  - smarty
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
+  - admonition
+  - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
+nav:
+  - Home: index.md
+  - Installation: installation.md
+  - OpenID Connect: setup/oidc.md
+  - RFCs: rfcs.md