Installation

Prerequisites

Make sure you have the following installed:

Rust (latest stable) — rustup.rs
Dioxus CLI — cargo install dioxus-cli --version 0.7.10 --locked
Bun — bun.sh (for Tailwind CSS)
Docker — for PostgreSQL and Mailpit

Quick Start

Clone the repository

bash

cd app

Bootstrap your env file

bash

just bootstrap

This copies .env.example to .env and generates a fresh SESSION_SECRET for you.

The defaults sign you in by email code (Mailpit catches the mail) with no identity provider to set up. Edit .env if you need to change:

DATABASE_URL — PostgreSQL connection string (default: postgres://lantern:lantern@localhost:5495/lantern)
BASE_URL — Your app's base URL (default: http://localhost:8080)
COMING_SOON — off by default; set true to enable the waitlist

Start infrastructure

bash

docker compose up -d

This starts:

PostgreSQL 18 on port 5495
Mailpit with SMTP on 1095 and web UI on 8095, where the sign-in codes arrive

Schema migrations in migrations/ are embedded in the binary and applied automatically on first boot.

FerrisKey is optional. just ferriskey starts one on port 8090 and creates the realm and client the app expects; see Authentication.

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

just ferriskey is the one optional extra: it starts FerrisKey from the ferriskey compose profile and runs scripts/ferriskey-bootstrap.sh against it.

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

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.

Warning

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:

bash

just rename my-new-project

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.