# {{name}}
A `rustio-admin` project. Generated by `rustio-admin new {{name}}`.
The wizard already wrote `.env` with a working local `DATABASE_URL`
and pre-filled your project name into the admin chrome. The
sections below pick up where the wizard's Next Steps left off.
## 1. First run
```sh
# 1. Create the database (only step the wizard cannot do for you).
createdb {{name}}_dev
# 2. Apply framework migrations and create your first admin.
rustio-admin migrate apply
rustio-admin user create --email admin@{{name}}.local --role administrator
# The CLI prompts twice for the password (echo-suppressed).
# Pass --password '...' only inside CI / scripted bootstrap.
# 3. Boot the project.
cargo run
```
Two URLs on first boot:
- <http://127.0.0.1:8000/> -- first-boot homepage. Replaceable:
edit `templates/home.html` (the three `--brand` / `--text` /
`--muted` CSS custom properties at the top are the obvious
customisation seam).
- <http://127.0.0.1:8000/admin> -- admin panel. Sign in with the
account from step 2.
> **Port already in use?** `src/main.rs` binds to `127.0.0.1:8000`.
> Change the literal in the `let addr = ...` line and re-run.
## 2. First model
The default scaffold ships with no domain models -- the admin panel
is ready, the homepage is alive, and you decide what the first
model represents.
```sh
# Declare your fields up front (recommended):
rustio-admin startapp patient \
--field name:str \
--field date_of_birth:timestamp \
--field doctor:fk:Doctor \
--field active:bool
# Or run interactively at a TTY (prompts one field per line):
rustio-admin startapp patient
# Or get the historical one-field placeholder model:
rustio-admin startapp patient --no-interactive
```
Field types (closed vocabulary): `str`, `text`, `int`, `bigint`,
`bool`, `timestamp`, `json`, `fk:<Model>`. Nullability, indexes,
unique constraints, and column defaults beyond the table above
are added by editing the generated migration.
The CLI prints the exact `mod` / `use` / `.model::<>()` lines to
paste into `src/main.rs`. After that:
```sh
rustio-admin migrate apply
cargo run
```
The `/admin/<names>` pages light up. Migrations are append-only
by contract -- once a file has run on any real database, treat it
as frozen and write a new numerically-prefixed file to move the
schema forward.
## 3. Admin usage
After signing in:
- `/admin` -- dashboard with per-model creation sparklines.
- `/admin/<model>` -- list / detail / create / edit pages.
- `/admin/history` -- typed audit trail, filterable by actor.
- `/admin/account/sessions` -- active sessions per user.
- `/admin/account/mfa/enroll` -- TOTP enrolment.
- `/admin/docs` -- framework docs, served locally.
- `/admin/health` -- live health view (web counterpart to
`rustio-admin doctor`).
Session-backed authentication uses Argon2id passwords; cookies
carry random tokens and the database stores SHA-256 hashes only.
Per-model permissions sit on a five-tier role ladder
(User · Staff · Supervisor · Administrator · Developer).
Every fresh database is seeded with three structural permission
groups (`administrator`, `editor`, `viewer`) -- they are
foundational defaults the project builds on, not throwaway
example data. `rustio-admin user create --role <name>` accepts those
three values (alongside the legacy five) and drops the new user
into the matching group on create. See
[`docs/design/DESIGN_PERMISSIONS.md`](https://github.com/abdulwahed-sweden/rustio-admin/blob/main/docs/design/DESIGN_PERMISSIONS.md)
for the grant matrix and the doctrine.
## 4. Common commands
```sh
rustio-admin doctor # health check
rustio-admin docs # probe local docs + print URLs
rustio-admin docs --open # open /admin/docs in your browser
rustio-admin migrate status # what's applied / pending
rustio-admin user list # show accounts
rustio-admin user role --email <e> administrator # promote a user
rustio-admin group create --name editors # create a group
rustio-admin perm grant-group --group editors --perm posts.add_post
```
## 5. Advanced topics
Production-grade surfaces ship with the framework and are worth
reading **before** you take a project to staging -- not on day one.
- **Multi-factor authentication (R3).** TOTP enrolment at
`/admin/account/mfa/enroll`. Backup codes printed once at
enrolment. AES-256-GCM-encrypted secrets via `RUSTIO_SECRET_KEY`
(generate with `openssl rand 32 | base64 | tr '+/' '-_' | tr -d '='`).
Make MFA mandatory by chaining
`.require_mfa(rustio_admin::auth::MfaPolicy::Required)` onto
`Admin::new()`.
- **Emergency recovery (R4 CLI).** When in-band recovery is closed
(password lost + MFA device lost + no other admin available), the
operator with shell + DB access runs `rustio-admin user reset-password
/ unlock / disable-mfa / promote / emergency-access` from this
README's parent directory. Every command renders a red banner
before mutating and writes one
`action_type = "emergency_recovery"` audit row.
- **Custom routes.** Mount your own handlers on `Router` BEFORE
`register_admin_routes` so the framework's `/admin/*` wildcards
don't shadow them. CSRF + correlation_id middleware applies
automatically.
- **Template overrides.** `rustio-admin override admin/<name>.html`
copies a framework template to `./templates/admin/<name>.html`
so you can edit it; pair with `RUSTIO_TEMPLATE_DIR=templates` at
runtime to make the override take effect.
See the framework's own
[`docs/getting-started.md`](https://github.com/abdulwahed-sweden/rustio-admin/blob/main/docs/getting-started.md)
and the
[`ModelAdmin` reference](https://github.com/abdulwahed-sweden/rustio-admin/blob/main/docs/modeladmin.md)
when you need more.
## Project layout
| Path | Purpose |
|---|---|
| `src/main.rs` | Boots the admin: connects to Postgres, applies migrations, registers models, mounts `/admin/*`, serves the homepage at `/`. |
| `templates/home.html` | First-boot homepage. Three CSS custom properties at the top control the surface colours. |
| `migrations/` | Numerically prefixed `*.sql` files. `rustio-admin migrate apply` runs every pending one transactionally. `rustio-admin startapp <name>` adds the first one. |
| `templates/admin/*.html` (optional) | Project-side overrides of any framework template. Set `RUSTIO_TEMPLATE_DIR=templates` to enable. |