Installation

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, Redis, and Mailpit

Quick Start

Clone the repository

bash

git clone https://github.com/your-org/dx-saas-template.git
cd dx-saas-template

Bootstrap your env file

bash

just bootstrap

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)
REDIS_URL — Redis connection string (default: redis://localhost:6379)
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

bash

docker compose up -d

This starts:

PostgreSQL on port 5432 (database dx_saas, user dx_saas)
Redis (Valkey) on port 6379
Mailpit with SMTP on 1025 and web UI on 8025

Schema migrations in migrations/ are applied automatically by sqlx::migrate! when the server starts.

Install frontend dependencies

bash

bun install

Run the development server

bash

dx serve --addr 0.0.0.0

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

Note

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

Core Settings

DATABASE_URL — PostgreSQL connection string (e.g. postgres://user:pass@host:5432/dbname)
REDIS_URL — Redis/Valkey connection string
BASE_URL — Public URL of your application
SESSION_SECRET — Hex-encoded session signing key (64+ bytes)
SECURE_COOKIES — Set to true in production (HTTPS)

FerrisKey Auth

FERRISKEY_URL — Base API URL (e.g., http://localhost:3333 or https://ferriskey.example.com/api)
FERRISKEY_ISSUER_URL — (Optional) Public OIDC issuer base URL
FERRISKEY_REALM — Realm name (e.g., myapp)
FERRISKEY_CLIENT_ID — OIDC client ID registered in the realm
FERRISKEY_CLIENT_SECRET — Client secret (allow authorization_code + client_credentials grants)
TRUST_PROXY_HEADERS — Set to true when behind a reverse proxy

Email (SMTP)

SMTP_HOST — SMTP server host
SMTP_PORT — SMTP port (default: 1025 for Mailpit)
SMTP_USER — SMTP username (optional for Mailpit)
SMTP_PASSWORD — SMTP password (optional for Mailpit)
SMTP_FROM — Sender email address

Sentry (optional)

Requires building with --features sentry.

SENTRY_DSN — Sentry project DSN
ENVIRONMENT — environment tag (e.g., development, production)

Renaming the project

After cloning, give the project its own name:

bash

just rename my-new-project

This rewrites the package name, PostgreSQL database name, tracing filter, Dockerfile binary path, and docs in one shot. Run cargo build afterwards to regenerate Cargo.lock.