Nittei

Overview

Nittei is a self-hosted calendar and scheduler server built upon nittei.

It supports authentication through

• API keys for server - server
• JSON Web Tokens for browser - server

Concepts

• Accounts: Accounts are the way to handle multi-tenancy. Each account can have multiple users
• Users: Users represent an actual user, and each one can belong to only one account
• Calendars: Users can each have multiple Calendars, which are used for grouping Calendar Events
• Calendar Events: Calendar Events are the actual events. They support recurrence rules and be flexible queried
• Reminders: Calendar Events can have reminders
• Freebusy: Users can be queried on their free busy
• Metadata: Calendars and Calendar Events can contain metadata values, allowing to store anything alongside them

More advanced features include

• Booking: Create a Service and register Users on it to make them bookable
• Integrations: Connect your Nittei, Google and Outlook calendars
• Webhooks: Notifying your server about Calendar Event reminders

Getting started

Prerequisites

As this application is written in Rust, you first need to have it installed. The easiest is to use Rustup and the instructions can be found on the official website. The command is the following:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

This project uses Just as a task manager. To install it, you can use Homebrew (MacOS & Linux)

brew install just

Once Rust and Just are installed, a few more utility tools can be installed by running

just install_tools

This will compile and install

• sqlx-cli: CLI used for applying the SQL migrations & for generating the offline files for SQLx
• cargo-pretty-test: CLI for running the tests and print them in a prettier way compared to cargo test
• cargo-watch: CLI for auto-reloading the backend when source files have changed

Initial setup

You can launch the Postgres container required for local development and execute the migration by running

just setup

Launching the server

Now we are ready to start the Nittei server

just dev

There are a few environment variables that can be used to control the server, see crates/utils/src/config.rs for more details.

Quick example of how to create and query a user

export SECRET_API_KEY="REPLACE ME WITH YOUR API KEY"

# Create a user with metadata
curl -X POST -H "Content-Type: application/json" -H "x-api-key: $SECRET_API_KEY" -d '{"metadata": { "groupId": "123" }}' http://localhost:5000/api/v1/user

# Get users by metadata
curl -H "x-api-key: $SECRET_API_KEY" "http://localhost:5000/api/v1/user/meta?key=groupId&value=123"

Please see below for links to more examples.

Running the tests

For running all the tests at once, you can run:

just test-all

This launches an ephemeral PostgreSQL container used by the tests. The script tries to remove the container at the end.

For running only the tests for the server (Rust) and the Rust client SDK, you can simply run:

just test

This also launches an ephemeral PostgreSQL container.

For running the tests for the JS client SDK, you first need to have the server running. As a reminder, this is the command:

just dev

Once it's running, the tests can be run by doing the following:

cd clients/javascript/
pnpm run test

OpenAPI UI

The API also provides an OpenAPI UI (Swagger) that allows to see, and test, all endpoints. When running the API in your local environment, you can find it at http://localhost:5000/swagger-ui/#/.

Additional tools

You can install additional tools by running

just install_all_tools

This will install

• cargo-outdated: CLI used to list the dependencies that are outdated
• cargo-udeps: CLI used to list the dependencies that are unused

Examples

• Calendars and Events

• Booking

• Reminders

• Creating JWT for end-users

Main Rust dependencies used

• Tokio: async runtime needed for using async/await
• Axum: HTTP framework
• validator + axum-valid: add validation step when deserializing structs and enums
• SQLx: async, pure Rust SQL crate featuring compile-time checked queries
• serde: serialization (and deserialization) framework
• anyhow: easy to use Error type for applications
• chrono: library providing structs/enums for handling datetimes and timezones
• rrule: library for generating instances of recurring events
• ts-rs: automatically generate Typescript types from Rust structs and enums
• tracing: handles tracing and logging
• tikv-jemallocator: replaces default memory allocator with Jemalloc

New to Rust

You can check docs/rust.md to get a small introduction to Rust.

Contributing

Contributions are welcome and are greatly appreciated!

License

MIT

Special thanks

• fmeringdal for the initial project. This repository is a fork adapted to our needs.