Scaffolding
Rustango hat zwei Ebenen der Codegenerierung — sodass du selten Boilerplate von Hand verdrahtest:
- Der Projektgenerator —
cargo rustango newerstellt ein komplett neues Projekt aus einer Vorlage. - Projektinterne Generatoren —
manage startappund diemanage make:*-Familie fügen Apps, Views, Serializer, Jobs und mehr in einem bestehenden Projekt hinzu.
Inhaltsverzeichnis
- Den Generator installieren
- Ein Projekt erstellen:
cargo rustango new - Was generiert wird
- Ein Feature-Modul hinzufügen:
manage startapp - Einzelne Dateien generieren: die
make:*-Befehle - Ein typischer Ablauf
Den Generator installieren
cargo rustango ist ein Cargo-Unterbefehl. Installiere ihn einmal, global:
cargo install cargo-rustango
Das legt ein cargo-rustango-Binary in deinem PATH ab; Cargo stellt es dann als cargo rustango bereit — ein globaler Befehl, der überall verfügbar ist, auch außerhalb eines Projekts. Dieselbe Installation bringt cargo-rgo mit, also ist cargo rgo … eine kürzere Schreibweise für jeden cargo rustango …-Befehl.
Die Version des Generators ist die, die dein Projekt bekommt
cargo rustango new schreibt rustango = "MAJOR.MINOR" in die generierte Cargo.toml — übernommen aus der Version des Generators, nicht aus dem, was gerade auf crates.io am neuesten ist. Welchen Generator du installierst, dessen Version pinnt dein Projekt.
Das ist fast immer das, was du willst, und genau deshalb ist der Installationsbefehl oben ungepinnt: Der neueste Generator schreibt den neuesten Pin, und die beiden können nicht auseinanderdriften.
Wissen solltest du es, wenn du bewusst ein älteres Release willst — um zu einem Projekt zu passen, das bereits darauf läuft, oder um einen Fehlerbericht zu reproduzieren. Pinne den Generator, nicht das Projekt:
cargo install cargo-rustango --version 0.57.0
Welchen du hast, prüfst du mit cargo rustango --version. Später aktualisieren ist derselbe Befehl mit --force, und das wirkt sich nur auf Projekte aus, die du danach generierst — der Pin eines bestehenden Projekts ist eine Zeile in dessen eigener Cargo.toml, die du selbst änderst.
Ein Projekt erstellen: cargo rustango new
cargo rustango new <name> [--template api|fullstack|tenant]
[--backend postgres|sqlite|mysql]
[--features <liste>]
<name>— der Projekt- (und Crate-)Name. Er muss ein gültiger Cargo-Crate-Name sein ([A-Za-z_][A-Za-z0-9_-]*), und das Zielverzeichnis darf noch nicht existieren.--template/-t— welcher Starter gescaffoldet wird (Default: fullstack).--backend/-b— auf welcher Datenbank das Projekt läuft (Default: postgres).--features/-F— zusätzliche Rustango-Features, durch Komma oder Leerzeichen getrennt.--alias rgo— die Abhängigkeitrgostattrustangonennen (siehe Ein kürzerer Name).--interactive/-i— stattdessen aus Menüs wählen. Ein nacktescargo rustango newauf einem Terminal macht dasselbe.--help/-h,--version— Verwendung und Version.
Ohne Argumente aufgerufen, fragt es nach:
rustango — new project
(enter accepts the default; ctrl-c aborts)
Project name: shop
Template
1) fullstack ORM + auto-admin + forms — the usual starting point (default)
2) api bare ORM + axum, no admin UI — for JSON-only services
3) tenant multi-tenancy: tenant registry + operator console
> 3
Database
1) postgres every feature, including schema-mode tenancy (default)
2) sqlite a file beside the project — no server to run
3) mysql MySQL 8.0+ / MariaDB
> 1
Extra features (numbers, e.g. `1 3 4` — enter for none)
1) csrf CSRF protection middleware for form POSTs
2) sso OIDC single sign-on for application users
…
> 1 2
Same thing without the wizard:
cargo rustango new shop --template tenant --backend postgres --features csrf,sso
Create it? [Y/n]
Der Wizard setzt genau die Felder, die auch die Flags setzen, und gibt die entsprechende Kommandozeile aus, bevor er irgendetwas schreibt — einmal benutzt, kennst du die Flags, und es gibt nur einen Codepfad, der entscheidet, was ein Projekt enthält. Ohne Terminal (Skript, CI-Job) bricht er mit einer Meldung ab, statt auf eine Antwort zu warten, die niemand geben kann.
Die drei Vorlagen
Jede entspricht einer der drei App-Formen von Rustango:
| Vorlage | Was du bekommst | Wähle sie, wenn |
|---|---|---|
api | Blankes ORM + Axum, kein Admin | JSON-only-Dienste und Microservices |
fullstack (Default) | ORM + der Auto-Admin | Eine typische Webapp mit Backoffice |
tenant | Multi-Tenancy + Operator-Konsole + Apps pro Tenant | SaaS, das viele isolierte Tenants hostet |
Benutzerkonten. Nur --template tenant hat eine Anmeldung für die eigenen Benutzer deiner App eingebaut. Mit api oder fullstack ist der Admin-Login nur für das Team; baue Registrierung und Login für deine Benutzer wie in Erste Schritte, Schritt 14.
cargo rustango new myblog # fullstack (the default)
cargo rustango new api_demo --template api
cargo rustango new shop --template tenant
Die Datenbank wählen: --backend
cargo rustango new edge --backend sqlite
cargo rustango new shop --backend mysql
--backend entscheidet, was cargo run benutzt, und formt das ganze Projekt passend dazu — die DATABASE_URL in .env.example, die Services in docker-compose.yml, die url in jeder Settings-Stufe und die Startanleitung im README. Nimm sqlite, und es gibt überhaupt keinen Datenbank-Service: sie ist eine Datei neben dem Projekt, die das erste cargo run -- migrate anlegt.
Alle drei Backends bleiben in den generierten [features] verdrahtet, die anderen beiden sind also ein Flag entfernt:
cargo run --no-default-features --features sqlite
Mehr vom Framework einschalten: --features
cargo rustango new saas --template tenant --features csrf,sso,cache-redis
Eine Vorlage schaltet einen sinnvollen Satz ein; --features ergänzt die Opt-ins, die keine von ihnen erreicht:
| Feature | Was es hinzufügt |
|---|---|
csrf | CSRF-Schutz-Middleware für Formular-POSTs |
sso / admin-sso | OIDC Single Sign-on, für App-Benutzer / für die Admin-Site |
passkey | WebAuthn-/Passkey-Authentifizierung |
cache-redis / cache-page | Redis-Cache-Backend / Caching ganzer Seiten |
jobs / jobs-postgres | Hintergrund-Job-Queue, prozessintern / datenbankgestützt und damit neustartfest |
scheduler | Hintergrundaufgaben in festen Intervallen |
email-smtp | SMTP-Transport für das E-Mail-Framework |
mcp | Model-Context-Protocol-Server für KI-Agenten (nur Tenant-Template) |
http2 | Klartext-HTTP/2 (h2c) neben HTTP/1 bereitstellen |
static-files / security-headers | Auslieferung statischer Dateien mit gehashten Asset-Namen / Security-Header und CSP-Builder, ohne Admin |
test-client | Prozessinterner HTTP-Testclient, ohne Admin |
testkit / test_utils | Nur-Test-Schema-Builder, Factories und Konstruktoren |
--features tenancy allein wählt --template tenant; mit einer anderen Vorlage wird es abgelehnt, weil nur die main.rs der Tenant-Vorlage Tenancy bedient. cargo rustango new --help gibt diese Liste aus. Backends sind hier nicht gültig — nimm dafür --backend. Eines als Feature zu nennen wird abgelehnt, weil es das Backend des Frameworks festnageln würde, während das eigene Feature des Projekts aus bliebe, und #[derive(Model)] seine Ausgaben an den Features des Projekts ausrichtet.
Ein kürzerer Name: rgo
cargo rgo new shop --alias rgo
--alias rgo trägt die Abhängigkeit unter dem Namen rgo ein, und der generierte Code verwendet rgo::-Pfade und #[rgo(...)]-Attribute. Die Crate rgo auf crates.io gehört jemand anderem, darum ist das eine Umbenennung des Pakets rustango:
[dependencies]
rgo = { package = "rustango", version = "0.67", default-features = false, features = ["batteries"] }
[features]
postgres = ["rgo/postgres"]
use rgo::prelude::*;
#[derive(Model, Debug, Clone)]
#[rgo(table = "item", display = "name")]
pub struct Item {
#[rgo(primary_key)]
pub id: Auto<i64>,
#[rgo(max_length = 64)]
pub name: String,
}
#[rgo(...)] bedeutet genau dasselbe wie #[rustango(...)] und funktioniert unabhängig davon, wie du die Abhängigkeit nennst. Ein Struct oder Feld verwendet einen Namen: #[rustango(...)] und #[rgo(...)] am selben Element zu mischen ist ein Compile-Fehler. manage startapp und die make:*-Generatoren lesen die Cargo.toml und schreiben ebenfalls rgo::-Pfade und #[rgo(...)].
Was generiert wird
Jede Vorlage schreibt ein in sich geschlossenes Cargo-Projekt:
<name>/
Cargo.toml # the rustango dependency + features for this template
.env.example # copy to .env (DATABASE_URL, RUSTANGO_SESSION_SECRET, …)
.gitignore
rust-toolchain.toml # selects the `stable` toolchain + rustfmt/clippy/rust-analyzer
docker-compose.yml # the database service (none for sqlite) + a cargo-watch dev container
Dockerfile # production image (multi-stage, release, non-root)
Dockerfile.dev # the dev image docker-compose.yml builds
.dockerignore
README.md
config/
default.toml # settings shared across every environment
dev_settings.toml # per-tier overrides …
staging_settings.toml
prod_settings.toml
migrations/ # JSON migration files (committed to git)
system/migrations/ # the framework's own tables, generated on first migrate (commit them)
src/
lib.rs # the app as a library: `pub mod models; pub mod urls; pub mod views;`
main.rs # the single binary — HTTP server + every manage verb
models.rs # your #[derive(Model)] structs
views.rs # request handlers ("views")
urls.rs # pub fn api() -> Router that aggregates your routes
Ein Binary für alles
src/main.rs ist der einzige Einstiegspunkt. Es startet den HTTP-Server und dispatcht jedes manage-Verb — es gibt kein separates manage-Skript und keine src/bin/manage.rs. Die Module liegen im Library-Target (src/lib.rs), daher erreicht main.rs sie über den Crate-Namen, und ebenso ein Worker-Binary unter src/bin/. Die main.rs der api-Vorlage, gekürzt:
use myapp::urls;
#[rustango::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let _ = dotenvy::dotenv();
rustango::manage::Cli::new()
.api(urls::api())
.with_health() // /health + /ready endpoints (every template)
.run()
.await
}
Also startet cargo run den Server, und cargo run -- <verb> führt Migrationen, Generatoren und den Rest aus.
Wie sich die Vorlagen innerhalb von main.rs / urls.rs unterscheiden:
- api — kein Admin;
urls::api()aggregiert schlicht deine eigenen Routen. - fullstack — dieselbe
urls.rs, plusadmin_prefix(&settings)und einadmin_router(pool, &settings)-Helfer, denmain.rsmitCli::try_nest_with(urls::admin_prefix(&settings), …)einhängt, gebaut aus dem Pool des Servers. Das Präfix ist[admin] url_prefix(oder[routes] admin_url), sonst/admin.main.rslädt die Einstellungen einmal und gibt sie mitwith_loaded_settingsan dieCliweiter. Er nimmtrustango::sql::Poolentgegen, benennt also keinen Treiber, und liegt hinter einem Login: Lege das Konto mitcargo run -- create-admin <username> --superuseran (siehe Erste Schritte, Schritt 11). - tenant —
main.rsergänzt.tenancy(), bedient die Operator-Konsole auf der Apex-Domain und jeden Tenant unter seiner eigenen Subdomain, sowie.with_tenant_provisioning("migrations")für die Konsolenseiten New tenant und Database servers (lösche es, um sie abzuschalten; das Speichern eines Servers brauchtRUSTANGO_SECRET_KEY). Die eigenen Tabellen des Frameworks werden beim erstencargo run -- migrateaus den kompilierten Modellen in einensystem/migrations/-Ordner generiert — kein handgeliefertes Bootstrap-JSON, sodass das allererste migrate ohne zusätzliche Einrichtung funktioniert.
Geschichtete Konfiguration
Die Einstellungen laden zuerst config/default.toml, dann config/<RUSTANGO_ENV>_settings.toml darüber. RUSTANGO_ENV ist standardmäßig dev, sodass ein frisch gescaffoldetes cargo run ohne Änderungen funktioniert; setze RUSTANGO_ENV=prod in der Produktion, um prod_settings.toml aufzunehmen.
Die Umgebung gewinnt immer über die Dateien. RUSTANGO__SECTION__KEY überschreibt [section] key, und einige Schlüssel haben zusätzlich eine eigene Umgebungsvariable, die über beiden steht: DATABASE_URL (oder die DB_*-Variablen) für [database] url, RUSTANGO_BIND für [server] bind, RUSTANGO_APEX_DOMAIN für [tenancy] apex_domain. Die Datenbank-URL kommt also aus DATABASE_URL / DB_*, dann RUSTANGO__DATABASE__URL, dann [database] url; die Prod-Stufe lehnt eine URL aus einer Einstellungsdatei ab. cargo run -- check --settings listet jeden Schlüssel und woher sein Wert kommt, Geheimnisse verborgen.
Die Dev- und Staging-Dateien setzen eine [brand] tagline von dev bzw. staging. Um sie zu ändern oder deinen eigenen Namen und dein Logo zu setzen, siehe Branding und die Konfigurationsschlüssel des Admins.
Einstellungen, die nicht von selbst wirken
Nicht jeden Schlüssel liest das Framework. Schlüssel ohne Wirkung wurden in 0.62.0 entfernt ([sso], [auth.jwt] issuer / audience, [admin] primary_color / csrf_cookie_secure / session_timeout_minutes); eine Datei oder RUSTANGO__*-Variable, die noch einen setzt, lädt nicht und nennt den Ersatz.
| Schlüssel | Status |
|---|---|
[audit] retention_days | Liest audit-cleanup ohne --days und --keep-last; plane dieses Kommando ein. |
[jobs], [i18n], [cache], [mail], [mcp], [auth.jwt]-TTLs, [admin] | Vom Benutzer verdrahtet: nur vom Konstruktor gelesen, den du aufrufst (jobs::inmemory_from_settings, Translator::from_settings, cache::from_settings_async, email::from_settings, mcp::secure_tenant_router_from_settings, auth_routes::Config::with_jwt_settings, admin::Builder::from_settings). |
Erster Lauf
cd <name>
cp .env.example .env # then change `postgres` -> `localhost` in DATABASE_URL
docker compose up -d --no-deps postgres # only the database: the rust service holds 8080
cargo run -- makemigrations # generate the framework's (and your) tables
cargo run -- migrate # apply them
cargo run -- create-admin admin --superuser # fullstack: the admin login (any username)
cargo run -- create-operator ops # tenant: the operator console login
cargo run # serve
cargo run -- --help # see every manage verb
Ein Feature-Modul hinzufügen: manage startapp
Scaffolde ein in sich geschlossenes Modul aus zusammengehörigen Modellen, Views und Routen:
cargo run -- startapp blog
Es schreibt src/blog/ mit mod.rs, models.rs (ein Starter-Modell, benannt nach der Singular-Form der App — blog → Blog), views.rs, urls.rs und tests.rs, deklariert dann das Modul in src/lib.rs (pub mod blog;; mod blog; in src/main.rs bei einem Projekt ohne lib.rs) und merged seine Routen in urls::api().
Optionen:
--into <dir>— scaffolde stattdessen untersrc/<dir>/(--into appsschreibtsrc/apps/blog/); die Zeilen für das Eltern-Modul undurls.rswerden zum Einfügen ausgegeben.--with-manage-bin— gib zusätzlich einesrc/bin/manage.rsaus (für Layouts, die ein separates manage-Binary bevorzugen).
Einzelne Dateien generieren: die make:*-Befehle
Innerhalb eines Projekts scaffolden die make:*-Verben jeweils eine Datei. Die vollständige Referenz pro Flag findest du in der manage-CLI-Referenz; die gängigen Formen sind:
| Befehl | Generiert |
|---|---|
make:viewset <Name> [--model <M>] | Ein CRUD-ViewSet |
make:serializer <Name> [--model <M>] | Ein Serializer zum Formen von Request/Response |
make:api_routes <app> | Ein API-Routen-Aggregator für eine App |
make:form <Name> | Ein HTML-Formular mit Validierung |
make:job <Name> | Ein Handler für einen Hintergrund-Job |
make:scheduled <Name> | Eine Aufgabe mit festem Intervall für scheduler::Scheduler |
make:worker <Name> | Ein Worker-Binary unter src/bin/, das die Job-Queue abarbeitet |
make:notification <Name> | Eine E-Mail-Benachrichtigung: ein Struct, das eine Email baut |
make:middleware <Name> | Ein Middleware-Gerüst |
make:test <Name> | Ein Testmodul mit dem In-process-Testclient |
cargo run -- make:viewset PostViewSet --model Post
cargo run -- make:serializer PostSerializer --model Post
cargo run -- make:test post_smoke
Ein typischer Ablauf
cargo rustango new myblog # 1. scaffold the project
cd myblog
cargo run -- startapp blog # 2. add a feature module
# …rename the starter `Blog` in src/blog/models.rs to `Post`, add fields…
cargo run -- makemigrations # 3. generate a migration
cargo run -- migrate # 4. apply it
cargo run -- make:viewset PostViewSet --model Post # 5. expose a JSON API
# …add `pub mod post_view_set;` to src/lib.rs and the `.nest_with` line from
# the end of src/post_view_set.rs to src/main.rs…
cargo run # 6. serve the URL make:viewset printed
