Iterate on documentation

README.md

@@ -22,3 +22,10 @@ a CalDAV/CardDAV server
 ## Getting Started
 
 - Check out the [documentation](https://lennart-k.github.io/rustical/installation/)
+
+## Tested Clients
+
+- DAVx5,
+- GNOME Accounts, GNOME Calendar, GNOME Contacts
+- Evolution
+- Apple Calendar (known issue: If a user is member of multiple groups then Apple Calendar just randomly selects a calendar home)

docs/index.md

@@ -11,10 +11,16 @@ If you still want to play around with it in its current state, absolutely feel f
 ## 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~~ (currently broken)
 - lightweight (the container image contains only one binary)
 - adequately fast (I'd love to say blazingly fast™ :fire: but I don't have any benchmarks)
 - deleted calendars are recoverable
 - Nextcloud login flow (In DAVx5 you can login through the Nextcloud flow and automatically generate an app token)
 - Apple configuration profiles (skip copy-pasting passwords and instead generate the configuration in the frontend)
 - [OpenID Connect](setup/oidc.md) support (with option to disable password login)
+
+## Tested Clients
+
+- DAVx5,
+- GNOME Accounts, GNOME Calendar, GNOME Contacts
+- Evolution
+- Apple Calendar (known issue: If a user is member of multiple groups then Apple Calendar just randomly selects a calendar home)

docs/installation.md

@@ -2,11 +2,13 @@
 
 ## Docker
 
+You can start a RustiCal container using the following command:
+
 ```sh
 docker run \
   -p 4000:4000 \
   -v YOUR_DATA_DIR:/var/lib/rustical/ \
-  -v YOUR_CONFIG_TOML:/etc/rustical/config.toml \ # (1)!
+  -v OPTIONAL_YOUR_CONFIG_TOML:/etc/rustical/config.toml \ # (1)!
   -e RUSTICAL__CONFIG_OPTION="asd" \  # (2)!
   ghcr.io/lennart-k/rustical
 ```
@@ -14,21 +16,44 @@ docker run \
 1. Mount config file
 2. Alternatively specify configuration using environment variables
 
+## User management
+
+In case you already have an OIDC server set up, see [here](setup/oidc.md) how to set up OIDC login and maybe skip this section.
+Otherwise you will have to use the `rustical principals` command.
+In Docker you can run this with
+
+```sh
+docker run --rm -it -v YOUR_DATA_DIR:/var/lib/rustical/ ghcr.io/lennart-k/rustical rustical principals
+```
+
+This is also the place to set up **groups**.
+Groups and rooms are also just principals and you can specify them as such using the `--principal-type` parameter.
+To assign a user to a group you can use the `rustical membership` command. Being a member to a principal means that you can completely act on their behalf and see their collections.
+
+**Note:** Apple Calendar doesn't play well with the current membership implementation so you might not want to set up groups at the moment.
+
+## Password vs app tokens
+
+The password is optional (if you have configured OpenID Connect) and is only used to log in to the frontend.
+Since it's sensitive information, a secure but slow hash algorithm (`argon2`) is chosen.
+
+App tokens are used by your CalDAV/CardDAV client (which can be managed through the frontend).
+I recommend to generate random app tokens for each CalDAV/CardDAV client.
+Since the app tokens are random they use the faster `pbkdf2` algorithm.
+
 ## Configuration
 
-RustiCal can be configured using either a `config.toml` file or environent variables.
+While RustiCal (apart from user management) will work without any configuration you should still know how to configure it. :)
 
-To see all configuration options available you can browse the [Cargo docs](/rustical/_crate/rustical/config/struct.Config.html).
+You can either mount a `config.toml` file or use environment variables.
 
-### TOML
+To see the options you can generate a default configuration using
-
-You can generate a default `config.toml` configuration using
 
 ```sh title="Generate default config.toml"
 rustical gen-config
 ```
 
-You'll have to set your database path to something like `/var/lib/rustical/db.sqlite3`.
+To see all configuration options available you can browse the [Cargo docs](/rustical/_crate/rustical/config/struct.Config.html).
 
 ### Environment variables
 
@@ -48,38 +73,6 @@ Every variable is
 - Dots become `__`
 - Arrays are JSON-encoded
 
-## Users and groups
-
-Next, you will want to set up your principals.
-Using the `rustical principals` command you can manage principals and passwords.
-
-Groups and rooms are also just principals and you can specify them as such using the `--principal-type` parameter.
-To assign a user to a group you can use the `rustical membership` command. Being a member to a principal means that you can completely act on their behalf and see their collections.
-
-You can also completely skip this and instead configure OpenID Connect.
-In that case your user will automatically be created when logging in through the frontend.
-
-## Password vs app tokens
-
-The password is optional (if you have configured OpenID Connect) and is only used to log in to the frontend.
-Since it's sensitive information,
-the secure but slow hash algorithm `argon2` is chosen.
-
-App tokens are used by your CalDAV/CardDAV client (which can be managed through the frontend).
-I recommend to generate random app tokens for each CalDAV/CardDAV client.
-Since the app tokens are random they use the faster `pbkdf2` algorithm.
-
-## WebDAV Push
-
-RustiCal supports [WebDAV Push](https://github.com/bitfireAT/webdav-push/) which can notify compatible clients like DAVx5 about changed calendar/addressbook objects.
-Since push messages are currently not encrypted you might potentially want to ensure that users only subscribe through your push server (e.g. [ntfy.sh](https://ntfy.sh/)), you can configure it the following:
-
-```toml
-[dav_push]
-# Must strictly be the URL origin (so no trailing slashes)
-allowed_push_servers = ["https://your-instance-ntfy.sh"]
-```
-
 ## Manual
 
 ```sh

docs/setup/oidc.md

@@ -13,7 +13,10 @@ client_secret = "secret..."
 claim_userid = "preferred_username"  # (1)!
 scopes = ["openid", "profile", "groups"]
 require_group = "app/rustical"  # (2)!
-allow_sign_up = false
+allow_sign_up = true
+
+[frontend]
+allow_password_login = false  # optional
 ```
 
 1. Can be either `preferred_username` or `sub`
@@ -32,3 +35,17 @@ identity_providers:
         redirect_uris:
           - https://rustical.example.com/frontend/login/oidc/callback
 ```
+
+### With environment variables
+
+```sh
+RUSTICAL_OIDC__NAME: "Authelia"
+RUSTICAL_OIDC__ISSUER: "https://auth.example.com"
+RUSTICAL_OIDC__CLIENT_ID: "rustical"
+RUSTICAL_OIDC__CLIENT_SECRET: "secret..."
+RUSTICAL_OIDC__CLAIM_USERID: "preferred_username"
+RUSTICAL_OIDC__SCOPES: '["openid", "profile", "groups"]'
+RUSTICAL_OIDC__REQUIRE_GROUP: "app:rustical"
+RUSTICAL_OIDC__ALLOW_SIGN_UP: "true"
+RUSTICAL_FRONTEND__ALLOW_PASSWORD_LOGIN: "false"
+```

mkdocs.yml

@@ -51,6 +51,7 @@ markdown_extensions:
   - pymdownx.superfences
   - admonition
   - attr_list
+  - pymdownx.tabbed
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg