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

Move stuff from README.md to docs

Browse Source
This commit is contained in:
Lennart
2025-04-17 22:21:04 +02:00
parent 2f685bbeed
commit 92322b9fcb
2 changed files with 59 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
README.md
View File

@@ -20,110 +20,3 @@ a CalDAV/CardDAV server
## Getting Started ## Getting Started
- Check out the [documentation](https://github.com) - Check out the [documentation](https://github.com)
## 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
RustiCal can either be configured using a TOML file or using environment variables.
You can generate a default `config.toml` with
```sh
rustical gen-config
```
> [!WARNING]
> The `rustical gen-config` command generates a random `frontend.secret_key`.
> This secret is used to generate session cookies so if it is leaked an attacker could use it to authenticate to against any endpoint (also when the frontend is disabled).
You'll have to set your database path to something like `/var/lib/rustical/db.sqlite3`.
### Environment variables
The options in `config.toml` can also be configured using environment variables. Names translate the following:
```toml
[data_store.toml]
path = "asd"
```
becomes `RUSTICAL_DATA_STORE__TOML__PATH`.
Every variable is
- uppercase
- prefixed by `RUSTICAL_`
- Dots become `__`
### Users and groups
Next, configure the principals by creating a file specified in `auth.toml.path` (by default `/etc/rustical/principals.toml`) and inserting your principals:
```toml
[[principals]]
id = "user"
displayname = "User"
password = "$argon2id$......."
app_tokens = [
{id = "1", name = "Token", token = "$pbkdf2-sha256$........"},
]
memberships = ["group:amazing_group"]
[[principals]]
id = "group:amazing_group"
user_type = "group"
displayname = "Amazing group"
```
Password hashes can be generated with
```sh
rustical pwhash
```
### Docker
You can also run the upper commands in Docker with
```sh
docker run --rm ghcr.io/lennart-k/rustical rustical gen-config
docker run -it --rm ghcr.io/lennart-k/rustical rustical pwhash
```
### 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"]
```

59
docs/installation.md
View File

@@ -35,6 +35,8 @@ You can generate a default `config.toml` configuration using
rustical gen-config rustical gen-config
``` ```
You'll have to set your database path to something like `/var/lib/rustical/db.sqlite3`.
### Environment variables ### Environment variables
The options in `config.toml` can also be configured using environment variables. The options in `config.toml` can also be configured using environment variables.
@@ -52,3 +54,60 @@ Every variable is
- prefixed by `RUSTICAL_` - prefixed by `RUSTICAL_`
- Dots become `__` - Dots become `__`
- Arrays are JSON-encoded - Arrays are JSON-encoded
## Users and groups
Next, configure the principals by creating a file specified in `auth.toml.path` (by default `/etc/rustical/principals.toml`) and inserting your principals:
```toml
[[principals]]
id = "user"
displayname = "User"
password = "$argon2id$......."
app_tokens = [
{id = "1", name = "Token", token = "$pbkdf2-sha256$........"},
]
memberships = ["group:amazing_group"]
[[principals]]
id = "group:amazing_group"
user_type = "group"
displayname = "Amazing group"
```
Password hashes can be generated with
```sh
rustical pwhash
```
## Docker
You can also run the upper commands in Docker with
```sh
docker run --rm ghcr.io/lennart-k/rustical rustical gen-config
docker run -it --rm ghcr.io/lennart-k/rustical rustical pwhash
```
## 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"]
```