Rustango-CMS
A page-tree content management system for Rust: describe a page type once, and editors get a form for it, a place in the site tree, a live preview, revisions and a public URL.
Built on rustango, axum and Tera. The CMS is a set of axum::Routers and Tera templates you merge into your own rustango app, so the rest of your site stays plain Rust.
It runs multi-tenant from the start โ every tenant gets its own page tree, media, users and settings โ and the same source boots on PostgreSQL, MySQL 8+ and SQLite.
๐ Docs: cms.rustango.com ยท in-repo guides ยท API reference ๐บ Tutorial: Build a ceramics shop โ a whole site, step by step, for editors and developers, with a runnable example.
Contents
- Features
- Install
- Quick start
- Try the demo
- Translations: chrome vs content
- Logging
- Cargo features
- Documentation
- Contributing
- License
Features
- Three ways to define content. Page types as Rust structs (
#[derive(PageType)]), page types built by editors in the admin with no code or migration, and reusable blocks (a StreamField body of headings, images, quotes, embeds, forms and your own#[derive(Block)]types). - An editor's admin at
/cms-admin/. Page tree with drag-and-drop, live preview, revisions and rollback, scheduled publishing and take-down, locking, approval workflows with email notifications, a media library with focal points and renditions, menus, categories, snippets, redirects, site settings and an accessibility checker. - Multi-language content. Locales per tenant, side-by-side translation screens for pages, snippets, forms and menus, and a localised admin (English, Ukrainian, Polish, French, German, Simplified Chinese and Japanese).
- A form builder. Multi-step forms with conditional logic, submissions stored per form, and notification email.
- Members and permissions. Roles and codename permissions for editors; private pages and sections for signed-in members, with sign-up, login and single sign-on.
- Headless when you want it. A read-only JSON API under
/api/v2/for a frontend you build yourself, with draft preview in the editor through short-lived preview links, and an MCP server so an AI agent can work in the CMS as a user, with its own keys. - Production pieces. SEO fields, sitemap, RSS/Atom feeds,
robots.txt, search (built-in or Elasticsearch), S3-compatible media storage, front-cache purging (Cloudflare, Varnish, CloudFront, Google Cloud CDN, Azure CDN) and CSRF protection on every admin form.
Install
[]
= "0.2"
= { = "0.61", = false, = ["admin", "auth_flows", "cache", "cache-page", "config", "email", "forms", "manage", "passwords", "runtime", "signals", "signed_url", "tenancy", "template_views"] }
= { = "0.8", = false, = ["tokio", "http1", "json", "form", "query"] }
= { = "1.20", = false }
= { = "1", = ["derive"] }
Pick the database with a feature: postgres is the default, and default-features = false, features = ["sqlite"] (or "mysql") switches it โ on both rustango-cms and rustango.
Use the same rustango minor version as the CMS (0.61 today). Two semver-incompatible copies give you two different Tenant and Pool types that do not unify. UPGRADING.md has the notes for each version.
The fastest start is the scaffolder, which writes a ready project for you โ see Getting started.
Quick start
A page type is a rustango model with a link to its page and one #[field] per box in the editor:
use Auto;
use ;
// Required; an empty impl keeps every default (parent/child rules,
// extra template context, โฆ).
Then merge the CMS routers into your manage runner:
use Path;
use Arc;
async
templates/article.html receives the page, its fields and the rendered body:
{{ page.title }}
{% if extension.photo %}{% endif %}
{{ _stream_html['body'] | safe }}
Generate the table with cargo run -- makemigrations and apply it with cargo run -- migrate-tenants. After that:
| Path | What answers |
|---|---|
/, /<slug>, /<slug>/<child> |
the public site โ each page rendered with its type's template |
/cms-admin/ |
the editor's admin (signed-in staff only) |
/api/v2/ |
the headless JSON API |
/sitemap.xml, /robots.txt, feeds |
generated from the published pages |
Page types register themselves at start-up. In a small binary, name each type once (let _ = std::any::type_name::<ArticlePage>();) so the linker cannot drop it. The complete, runnable version of this is examples/cms_demo; the developer chapters of the tutorial cover the other helpers (menus, library types, taxonomies, site settings).
Try the demo
The demo runs on SQLite, so there is no database server to install โ the registry and each tenant are files:
ARGS="--no-default-features --features sqlite --example cms_demo"
RUSTANGO_APEX_DOMAIN=localhost
Sign in at http://demo.localhost:8080/login as admin, then open http://demo.localhost:8080/cms-admin/. Browsers resolve *.localhost to your own machine; for curl, pass -H 'Host: demo.localhost'. RUSTANGO_BIND changes the default 0.0.0.0:8080.
PostgreSQL (the default feature): createdb rcms_demo, DATABASE_URL=postgres://localhost/rcms_demo, drop ARGS's feature flags and leave out --mode database --database-url โฆ. MySQL 8+: use the mysql feature and mysql://user:pass@host/db URLs, and create the databases first.
Create pages in /cms-admin/, not in the generic rustango admin at /__admin/ โ only the CMS admin builds the tree paths and checks the page-type rules.
The ceramics shop is the larger example: the site the tutorial builds, with product pages, categories, an order form, a members area, a second language and a sale.
Translations: chrome vs content
Templates have two translation tools. Pick by where the text comes from:
translate (rustango) |
t (CMS) |
|
|---|---|---|
| For | text you typed into the template โ buttons, headings | text from the database โ this page's title, body, lead |
| Stored in | a message catalog, keyed by the text itself | cms_translation rows, per page, locale and field |
| Locale | the request's LANG |
resolved for the active locale before render |
{# chrome โ the same label on every page #}
{{ translate(key="Save changes") }}
{# content โ THIS page's title #}
{{ page.title | t(field="title", translations=translations) }}
{# content in a loop โ each child against its own row #}
{% for c in children %}
{{ c.title | t(field="title", by_page=translations_by_page, page_id=c.id) }}
{% endfor %}
Both fall back to the original text when a translation is missing, so a half-translated site still renders. Register them once when you build Tera:
register; // `translate`
register_tera_filter; // `t`
Logging
#[rustango::main] installs a tracing subscriber (info,sqlx=warn by default). Change it with RUST_LOG:
RUST_LOG=info,rustango_cms::render=debug
docs/logging.md lists every log target and shows JSON logs for production and the OpenTelemetry setup.
Cargo features
| Feature | Effect |
|---|---|
postgres (default), sqlite, mysql |
Database backend, forwarded to rustango |
storage_s3 |
S3-compatible media storage (AWS S3, Cloudflare R2, MinIO, โฆ) |
cache_cloudflare, cache_varnish, cache_cloudfront, cache_gcp, cache_azure |
Purge a front cache when pages are published |
search_elasticsearch |
Elasticsearch as the search backend |
avif |
AVIF image renditions (pulls an AV1 encoder; slower build) |
test_utils |
Tenant::for_test for your integration tests |
Documentation
- cms.rustango.com โ everything below, as a website.
- What is Rustango-CMS? and Getting started โ from an empty folder to a blog in about 20 minutes.
- For editors โ find your way, your first page, live preview.
- Build a ceramics shop โ the tutorial, 16 editor chapters and 4 developer chapters, including a headless storefront with draft preview.
- Run it in production โ secrets, migrations, the reverse proxy, S3 media, caching, search and email.
- Headless API, per-tenant templates, Google sign-in.
- API reference on docs.rs โ every module, trait and type.
- CHANGELOG.md and UPGRADING.md.
Contributing
Issues and pull requests are welcome โ CONTRIBUTING.md explains the local checks a change must pass. Please report security problems privately, as described in SECURITY.md.
License
Dual-licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.
The admin embeds third-party assets under their own licences โ TipTap,
ProseMirror and CodeMirror (MIT), axe-core (MPL-2.0), the Hanken Grotesk and
Literata fonts (SIL OFL 1.1) and Material Symbols (Apache-2.0). Their notices
are in THIRD-PARTY-NOTICES.txt,
which is compiled into the binary and served at
/cms-admin/static/vendor/THIRD-PARTY-NOTICES.txt.
The example shop (examples/ceramics_shop) ships compiled Tailwind CSS
3.4.19 (MIT, notice kept in static/shop.css) and photos from Wikimedia
Commons under CC0, CC BY 4.0 and CC BY-SA 4.0 โ see
its photo credits. The
screenshots in docs/img/shop show those photos.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.