nikdoof/rustical
1
1
Fork 0
mirror of https://github.com/lennart-k/rustical.git synced 2025-12-13 12:22:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Iterate on documentation

Browse Source
This commit is contained in:
Lennart
2025-06-11 21:13:06 +02:00
parent 4eb35d6c0d
commit 6ecdc6125e
5 changed files with 65 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
README.md
View File

@@ -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)

8
docs/index.md
View File

@@ -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)

71
docs/installation.md
View File

@@ -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

19
docs/setup/oidc.md
View File

@@ -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"
```

1
mkdocs.yml
View File

@@ -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