diff --git a/README.md b/README.md index a064e20..02f8ac4 100644 --- a/README.md +++ b/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) diff --git a/docs/index.md b/docs/index.md index 3aa2d78..cb2222b 100644 --- a/docs/index.md +++ b/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) diff --git a/docs/installation.md b/docs/installation.md index 9f191c8..3ba5ba6 100644 --- a/docs/installation.md +++ b/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 - -You can generate a default `config.toml` configuration using +To see the options you can generate a default 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 diff --git a/docs/setup/oidc.md b/docs/setup/oidc.md index 8f76fc2..295bec0 100644 --- a/docs/setup/oidc.md +++ b/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" +``` diff --git a/mkdocs.yml b/mkdocs.yml index f778997..0bb4c2b 100644 --- a/mkdocs.yml +++ b/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