Getting started

Introduction

What Cadmus is, what you get from it, and how its pieces fit together.

Cadmus is a batteries-included web framework for Rust. You describe your data once, as models, and Cadmus gives you:

• a database table for each model, kept up to date with migrations;
• an admin site where people log in and add, edit, search and delete records;
• a REST API (JSON) so other programs can do the same, with interactive documentation;
• accounts and permissions: users, groups, two-factor login, login with Google, GitHub and others, and API keys for programs;
• management commands such as migrate and createsuperuser;
• file uploads, to a folder or to cloud storage.

It runs on axum, the web server, and SeaORM, the database layer, and works with SQLite, PostgreSQL and MySQL.

#Why Cadmus

• Batteries included. Accounts, permissions, an admin site, an API with documentation, migrations and file uploads come with the framework, configured in one settings file. There is nothing to choose and wire together before you can start.
• Little code to write. There are no HTML templates for the admin and no handlers for the API: both are generated from the models. Your own code goes where the generated parts stop.
• Caught early. It is Rust, so a misspelt setting, field or model is reported when the project compiles, before anything runs.
• One program to deploy. The result is a single fast executable, with no interpreter or runtime to install on the server.

#How the pieces fit

            your models (src/models/*.rs)
                        │
        ┌───────────────┼────────────────┬──────────────────┐
        ▼               ▼                ▼                  ▼
  database tables   admin site       REST API          API documentation
  (migrations)      /admin           /api/...          /api/docs
                        │                │
                        └──── accounts and permissions ────┘

Everything shares one set of rules: an account that may not change posts cannot change them in the admin or through the API, and neither sees buttons or endpoints it cannot use.

#Two crates

#Status

Cadmus is at version 0.1. Everything described here works and is tested on all three databases, but details may still change between versions. What is not there yet is listed under Limitations.

Next: build your first project.