Examples and generated starters

The repository examples and CLI starters serve different purposes:

No example is expected to exercise 100% of workspace behavior. External provider paths use deterministic mock credentials so CI and local development do not make live purchases, send email, or call cloud LLMs.

Blog showcase

The blog package demonstrates:

• server-rendered HTML and Active Record persistence;
• a parameterized repository query;
• a LiveView/WebSocket presentation example (Wasm islands are covered by cargo rullst make:island and the islands tutorial, not by this showcase);
• Pico CSS and a small embedded file-template fixture (include_str! plus fixed placeholder replacement; not Tera or another template engine);
• Billable quota evaluation and offline Stripe/InfinitePay adapter fixtures;
• bounded security-helper demonstrations and a local AI/vector fixture;
• pages that render under the unrelaxed production Content Security Policy, with same-origin stylesheets, scripts and vendored HTMX/Pico.css files;
• a debug-only standalone Studio and Nexus access that is loopback-only in debug builds and credential-protected in release builds.

The complete, current route list is maintained in examples/blog/README.md alongside its configuration requirements.

Small SaaS example

The SaaS example installs the source CLI, generates the starter and adds a small notes API using database-owned membership, parameterized SQL and owner authorization. Its interactive mode opens a disposable loopback application:

python3 examples/saas/run.py --serve

Follow examples/saas/README.md to register a user, grant local membership and call the notes API. Without --serve, the same command runs its automated authentication, isolation, CSRF, persistence/restart and revocation journey. The script requires Linux, Python 3.11+, the pinned toolchain and 32 GiB of initial disk headroom. It removes generated data on exit and uses no real provider account. This directory holds the canonical example recipe and resource; it is not a duplicate checked-in copy of a generated application.

LMS, ERP and Portfolio examples

Until 13.0.0-alpha.4, cargo rullst new --blueprint lms|erp|portfolio generated these applications; the CLI now offers only the Blank, API and SaaS starters, and --blueprint lms, erp, portfolio or blog fails before writing anything with a report that names the example. Each was generated with that CLI (SQLite, --default), then adapted to the workspace: publish = false, workspace dependencies, a library with router() plus a thin binary, and the generated tests (security baseline, CSRF, rate limits, ownership checks) as the package’s own tests.

Run one from its directory, so the server finds .env, Rullst.toml and its static files:

cd examples/lms
cp .env.example .env   # then set APP_KEY to 32 random characters, e.g. `openssl rand -hex 16`
cargo run -p rullst-lms-example -- db:migrate
cargo run -p rullst-lms-example

The ERP and Portfolio examples work the same way with rullst-erp-example and rullst-portfolio-example.

To start your own application from one, copy the directory and replace its workspace = true dependencies with the published crates (each README shows the line). Applications generated earlier from these blueprints keep working: their code is theirs.

Browser graphics example

The WebGPU example serves embedded HTML, CSS and JavaScript modules behind Rullst’s production CSRF/WAF/secure-header baseline. From the repository root:

cargo run --locked -p rullst-webgpu-example

Then open http://127.0.0.1:3007/webgpu/. All computation stays in the browser; missing WebGPU support selects the Canvas fallback. Follow examples/webgpu/README.md for the reusable modules and browser tests.

Blog tenant selection

The blog example inserts a static test-only TenantMembership before the tenant layer. The X-Tenant-ID header can select only one of those fixed memberships. This models the separation between an untrusted selector and trusted authenticated claims. Handlers read the membership-checked TenantContext that TenantLayer inserts. The Post model declares tenant_column, so its generated queries fail closed outside with_tenant(...); the hand-written repository SQL binds the same tenant itself.

In a real application, authentication middleware must derive membership from a verified session or token. Never construct membership from the same client header used to select a tenant.

Provider fixtures

The /pricing page uses mock_* credentials and performs no live checkout. It lists only the built-in Stripe and InfinitePay (experimental) adapters.

Mock URLs and sample provider metadata are test fixtures, not a promise of live capability, pricing, tax treatment, or regional availability.

Running locally

cd examples/blog
cargo run -p rullst-blog-example

Before local startup, configure APP_KEY in examples/blog/.env as documented in the example README. The showcase selects its database like Server and the Artisan commands (DATABASE_URL, .env, then Rullst.toml), so DATABASE_URL is optional locally and honored in deployments. The debug build needs no Nexus password, but verifies the socket peer as loopback. A release build does not start Studio and refuses to construct Nexus without validated NEXUS_ADMIN_USERNAME and NEXUS_ADMIN_PASSWORD values. Studio is local developer tooling; keep it on a trusted interface.

Verifying examples and starters

For the checked-in examples, run package tests and the workspace trifecta. For CLI output, use a temporary directory and verify every generated project:

cargo fmt --all -- --check
cargo check --all-features
cargo test --all-features

CI smoke or DAST workflows cover only the routes and assertions present in those files. Their logs, commit digest, toolchain, and skipped steps are the evidence; the example itself is not evidence of production readiness.