Installation
Set up your development environment and run the DX SaaS Template locally
Prerequisites
Make sure you have the following installed:
- Rust (latest stable) — rustup.rs
- Dioxus CLI —
curl -sSL http://dioxus.dev/install.sh | sh - Bun — bun.sh (for Tailwind CSS)
- Docker — for PostgreSQL and Mailpit
Quick Start
Clone the repository
Bootstrap your env file
This copies .env.example to .env and generates a fresh SESSION_SECRET for you.
Then edit `.env` to set the rest:
- `DATABASE_URL` — PostgreSQL connection string (default: `postgres://dx_saas:dx_saas@localhost:5432/dx_saas`)
- `FERRISKEY_URL` / `FERRISKEY_REALM` / `FERRISKEY_CLIENT_ID` / `FERRISKEY_CLIENT_SECRET` — Your FerrisKey instance, realm, and OIDC client
- `BASE_URL` — Your app's base URL (default: `http://localhost:8080`)
Start infrastructure
This starts:
- PostgreSQL 18 on port 5432
- Mailpit with SMTP on 1025 and web UI on 8025
Schema migrations in `migrations/` are embedded in the binary and applied automatically on first boot.
Install frontend dependencies
Run the development server
The app will be available at http://localhost:8080. The dev server auto-reloads on code changes and runs Tailwind CSS automatically.
Project Commands
| Command | Description |
|---|---|
dx serve --addr 0.0.0.0 |
Start development server with hot reload |
dx build --release --platform web |
Production build |
bunx @tailwindcss/cli -i tailwind.css -o ./assets/tailwind.css |
Build Tailwind CSS manually |
cargo fmt --all -- --check |
Check formatting |
cargo clippy --workspace --all-targets -- -D warnings |
Lint |
cargo machete |
Detect unused dependencies |
The dx serve command automatically compiles Tailwind CSS. You only need to run the Tailwind CLI manually for CI builds or when dx serve is not running.
Environment Variables
Changing the database schema
Queries use sqlx's compile-time-checked macros, so column names and types are
verified against the schema when you build. The metadata lives in .sqlx/ and is
committed, which is what lets a fresh clone build with no database running.
After editing any SQL or adding a migration, regenerate the metadata:
docker compose up -d
cargo sqlx prepare -- --no-default-features --features server
Editing a query without re-preparing fails the next build. Editing a migration without re-preparing does not — cached entries are keyed by the query text, so untouched queries keep matching now-stale metadata and compile fine, failing only at runtime. CI guards this by building against a real database.
Renaming the project
After cloning, give the project its own name:
This rewrites the package name, Postgres database/user name, tracing filter, Dockerfile binary path, and docs in one shot. Run cargo build afterwards to regenerate Cargo.lock.