rustango-cms 0.4.0

A page-tree content management system for Rust, built on rustango
Documentation
# 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](https://github.com/ujeenet/rustango), [axum](https://github.com/tokio-rs/axum) and [Tera](https://keats.github.io/tera/).** The CMS is a set of `axum::Router`s 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](https://cms.rustango.com) ยท [in-repo guides](docs/) ยท [API reference](https://docs.rs/rustango-cms)
๐Ÿบ **Tutorial:** [Build a ceramics shop](https://cms.rustango.com/shop-overview) โ€” a whole site, step by step, for editors and developers, with a [runnable example](examples/ceramics_shop/).

โญ **Like it? Star [Rustango-CMS](https://github.com/ujeenet/rustango-cms) and [Rustango](https://github.com/ujeenet/rustango) on GitHub.** Stars help other Rust developers find both projects.

---

## Contents

- [Features]#features
- [Install]#install
- [Quick start]#quick-start
- [Try the demo]#try-the-demo
- [Translations: chrome vs content]#translations-chrome-vs-content
- [Logging]#logging
- [Cargo features]#cargo-features
- [Documentation]#documentation
- [Contributing]#contributing
- [License]#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

```toml
[dependencies]
rustango-cms = "0.4"
rustango     = { version = "0.65", default-features = false, features = ["admin", "auth_flows", "cache", "cache-page", "config", "email", "forms", "manage", "passwords", "runtime", "signals", "signed_url", "tenancy", "template_views"] }
axum         = { version = "0.8", default-features = false, features = ["tokio", "http1", "json", "form", "query"] }
tera         = { version = "1.20", default-features = false }
serde        = { version = "1", features = ["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.65 today). Two semver-incompatible copies give you two different `Tenant` and `Pool` types that do not unify. [UPGRADING.md](UPGRADING.md) has the notes for each version.

The fastest start is the scaffolder, which writes a ready project for you; then `cargo run -- quickstart` creates a local SQLite site and starts it, the same in bash and Windows PowerShell. See [Getting started](docs/getting-started.md). Add `--theme blog`, `news`, `portfolio` or `blog-portfolio` for a finished-looking site with pages, menus and colours, and no Rust models: see [Starter themes](docs/themes.md).

## Quick start

A page type is a rustango model with a link to its page and one `#[field]` per box in the editor:

```rust
use rustango::sql::Auto;
use serde::{Deserialize, Serialize};

#[derive(rustango::Model, rustango_cms::PageType, Default, Debug, Clone, Serialize, Deserialize)]
#[rustango(table = "blog_article", app = "blog")]
#[page_type(type_name = "ArticlePage", verbose_name = "Article", template = "article.html")]
pub struct ArticlePage {
    #[rustango(primary_key)]
    pub id: Auto<i64>,
    #[rustango(fk = "cms_page", on = "id", unique)]
    pub page_id: i64,
    #[field(widget = MediaPicker, label = "Photo")]
    pub photo: Option<i64>,
    #[field(widget = Stream, label = "Body", allowed(heading, paragraph, image, quote))]
    pub body: Option<String>,
}

// Required; an empty impl keeps every default (parent/child rules,
// extra template context, โ€ฆ).
impl rustango_cms::PageTypeOverrides for ArticlePage {}
```

Then merge the CMS routers into your `manage` runner:

```rust
use std::path::Path;
use std::sync::Arc;

#[rustango::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut tera = tera::Tera::new("templates/**/*.html")?;
    rustango_cms::admin::register_templates(&mut tera)?;
    rustango_cms::block::tera_helpers::register_tera_function(&mut tera);
    let tera = Arc::new(tera);

    // The CMS ships its migrations; this copies them next to yours.
    let migrations = Path::new(env!("CARGO_MANIFEST_DIR")).join("migrations");
    rustango_cms::migrations::materialize(&migrations)?;

    // The admin router has no auth of its own โ€” always wrap it.
    let admin = rustango_cms::admin::public_router(tera.clone()).merge(
        rustango_cms::admin::with_login_required(rustango_cms::admin::router(tera.clone()), "/login"),
    );
    let app = admin
        .merge(rustango_cms::api::router())
        .merge(rustango_cms::rendition_route::router())
        .merge(rustango_cms::router(tera)); // public pages: claims every other path

    let csrf = rustango::forms::csrf::CsrfConfig::default()
        .exempt_prefix(rustango_cms::analytics::COLLECT_PATH)
        .exempt_prefix(rustango_cms::api::PREFIX)
        .allow_insecure_for_dev(); // local http only โ€” remove in production

    rustango::manage::Cli::new()
        .tenancy()
        .api(app)
        .migrations_dir(migrations)
        .with_csrf_config(csrf)
        .seed(|registry| {
            let pool = registry.clone();
            async move { rustango_cms::ensure_seeded(&pool).await?; Ok(()) }
        })
        .run()
        .await
}
```

`templates/article.html` receives the page, its fields and the rendered body:

```html
<article>
  <h1>{{ page.title }}</h1>
  {% if extension.photo %}<img src="{{ rcms_image_url(media_id=extension.photo, filter='fill-1200x600') }}" alt="">{% endif %}
  {{ _stream_html['body'] | safe }}
</article>
```

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`](examples/cms_demo/); the [developer chapters](docs/shop-dev-helper-traits.md) 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:

```sh
export DATABASE_URL="sqlite:./var/registry.db?mode=rwc"
ARGS="--no-default-features --features sqlite --example cms_demo"

cargo run $ARGS -- migrate-registry
cargo run $ARGS -- create-tenant demo \
    --mode database \
    --database-url "sqlite:./var/demo.db?mode=rwc" \
    --host-pattern demo.localhost
cargo run $ARGS -- create-user demo admin --password 'change-me-please' --superuser
RUSTANGO_APEX_DOMAIN=localhost cargo run $ARGS -- runserver
```

In Windows PowerShell, set the variables with `$env:` and pass the flags as an array:

```powershell
$env:DATABASE_URL = "sqlite:./var/registry.db?mode=rwc"
$env:RUSTANGO_APEX_DOMAIN = "localhost"
$a = "--no-default-features", "--features", "sqlite", "--example", "cms_demo"

cargo run @a -- migrate-registry
cargo run @a -- create-tenant demo --mode database --database-url "sqlite:./var/demo.db?mode=rwc" --host-pattern demo.localhost
cargo run @a -- create-user demo admin --password 'change-me-please' --superuser
cargo run @a -- runserver
```

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](examples/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 |

```html
{# chrome โ€” the same label on every page #}
<button>{{ translate(key="Save changes") }}</button>

{# content โ€” THIS page's title #}
<h1>{{ page.title | t(field="title", translations=translations) }}</h1>

{# content in a loop โ€” each child against its own row #}
{% for c in children %}
  <a href="{{ c.url_path }}">{{ c.title | t(field="title", by_page=translations_by_page, page_id=c.id) }}</a>
{% 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:

```rust
rustango::i18n::tera_tags::register(&mut tera, translator); // `translate`
rustango_cms::translation::register_tera_filter(&mut tera); // `t`
```

## Logging

`#[rustango::main]` installs a `tracing` subscriber (`info,sqlx=warn` by default). Change it with `RUST_LOG`:

```sh
RUST_LOG=info,rustango_cms::render=debug cargo run   # one module in detail
```

[docs/logging.md](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]https://cms.rustango.com** โ€” everything below, as a website.
- **[What is Rustango-CMS?]docs/cms-overview.md** and **[Getting started]docs/getting-started.md** โ€” from an empty folder to a blog in about 20 minutes.
- **For editors** โ€” [find your way]docs/admin-find-your-way.md, [your first page]docs/admin-first-page.md, [live preview]docs/admin-live-preview.md.
- **[Build a ceramics shop]docs/shop-overview.md** โ€” the tutorial, 16 editor chapters and 4 developer chapters, including [a headless storefront]docs/shop-dev-headless.md with [draft preview]docs/shop-dev-headless-preview.md.
- **[Run it in production]docs/production.md** โ€” secrets, migrations, the reverse proxy, S3 media, caching, search and email.
- **[Headless API]docs/api.md**, **[per-tenant templates]docs/tenant-templates.md**, **[Google sign-in]docs/sso-google-setup.md**.
- **[API reference on docs.rs]https://docs.rs/rustango-cms** โ€” every module, trait and type.
- [CHANGELOG.md]CHANGELOG.md and [UPGRADING.md]UPGRADING.md.

## Contributing

Issues and pull requests are welcome โ€” [CONTRIBUTING.md](CONTRIBUTING.md) explains the local checks a change must pass. Please report security problems privately, as described in [SECURITY.md](SECURITY.md).

If Rustango-CMS saves you time, the simplest way to help is a star on [Rustango-CMS](https://github.com/ujeenet/rustango-cms) and on the framework under it, [Rustango](https://github.com/ujeenet/rustango).

## License

Dual-licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE]LICENSE-APACHE)
- MIT license ([LICENSE-MIT]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](src/admin/static/vendor/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](examples/ceramics_shop/photos/CREDITS.md). 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.