Tutorial
This tutorial builds a todo service step by step: a domain with commands, queries, a report, a custom endpoint, authentication, and permissions. It starts where the Quick start ends, and splits the code into a domain crate and a service crate.
Before you start
You should be comfortable with Rust, async code on tokio, and HTTP APIs. You need the
prerequisites installed and a Postgres database reachable
through RIVERBASE_DB_URL.
Chapters
| # | Chapter | You will learn |
|---|---|---|
| 1 | Key concepts | Domains, namespaces, engines, the HTTP surface, auth vs authorization |
| 2 | Scaffold and domain | Crate layout, domain!, DomainRuntime, mount_domain |
| 3 | Commands | command_engine!, aggregates, #[domain_action], invoking over HTTP |
| 4 | Queries | query_resource!, report_resource!, query_engine! |
| 5 | Custom endpoints | Domain routes, app-level routers, route access |
| 6 | Auth and users | MockAuth, Keycloak/OIDC, profiles |
| 7 | Permissions | Casbin activities and row-level scope_policy |
| 8 | Run and verify | Migrate, run, and walk a curl checklist |
| 9 | Secure defaults | The checks a production service must pass |
Out of scope here
- Running an identity provider. Riverbase consumes identity from Keycloak or another OIDC IdP; it is not a user directory.
- The extension crates for workers, media files, and forms. Each has its own page under Crates.
- Production topology. See Deployment.