Prerequisites & first project

• Rust 1.94+ — install rustup
• A database: SQLite (nothing to install, the default), PostgreSQL 12+, or MySQL / MariaDB

rustc --version    # 1.94 or later

cargo install runique --features sqlite --locked

The CLI connects to the database (create-superuser): it must be compiled with your engine's driver. Replace sqlite with postgres, mysql or mariadb, or use all-databases for a binary that talks to all three. Without an engine feature, every connection fails with "driver not enabled".

--locked uses the dependency versions published with the crate; without it, Cargo may pick newer versions that don't work together.

To switch engines later, reinstall with --force:

cargo install runique --features postgres --locked --force

runique new my_project
cd my_project

The name may only hold letters, digits, _ and -, can't start with a digit or -, and can't be a reserved name (a Rust keyword, std, core, test, a Windows device name such as con, or migration / runique, already taken in the generated project).

runique new writes a complete project, ready to run:

my_project/
├── Cargo.toml          workspace: the app + its `migration` crate
├── .env                settings, with a random SECRET_KEY of its own
├── migration/          the migration crate (Cargo.toml, src/main.rs, src/lib.rs)
├── src/
│   ├── main.rs         the application builder
│   ├── url.rs          the routes (/, /signup, /login, /logout, /about)
│   ├── views.rs        the views
│   ├── forms/          sign up and sign in forms
│   └── entities/       your models (model!)
├── templates/          base.html (the layout), index, about, signup, login
├── static/css/
└── media/              favicon, logo, and the files users upload

The project uses SQLite by default. For another engine, see Database.

runique migration up

The migration/ crate already holds the migrations of the framework's tables (eihwaz_users, sessions, rights, history, reset tokens). This command applies them. The first run compiles the crate, so it takes a while; later runs are quick.

Skip this step and the app still starts, but the first request touching a session fails with no such table: eihwaz_sessions.

cargo run

Expected output:

   Runique is operational
      └──>  Server launched on http://127.0.0.1:3000
          └──>  Connected to database Sqlite -> data.db
              └──> ctrl + c to stop

The home page comes with sign up, sign in and sign out.

runique create-superuser

See Runique CLI. The admin panel also needs the admin feature: see Admin.

runique new writes it for you:

IP_SERVER=127.0.0.1
PORT=3000

# `dev` or `prod`: sets how the application behaves (session cookie, startup checks,
# public URL, allowed hosts, template reload, logs). Unset or unknown: `prod`.
RUNIQUE_ENV=dev

# Shows the detailed error pages, and changes nothing else. It also works with
# RUNIQUE_ENV=prod to look into a problem on a live site, but every visitor then sees those
# pages: not recommended, turn it off as soon as you're done.
DEBUG=true

# Signs the CSRF tokens and the sessions: this project's own, keep it secret
SECRET_KEY=<64 hex characters generated by runique new>

DB_ENGINE=sqlite
DB_NAME=data.db
DATABASE_URL="sqlite://data.db?mode=rwc"

The SECRET_KEY is generated at random when the project is created. If you need to replace it (leak, new deployment), any random string of 32 characters or more will do, for instance:

openssl rand -hex 32

In production (RUNIQUE_ENV=prod), Runique refuses to start with a key that is missing, too short, or left at its example value.

The other variables (templates, static and media folders, logging…) have defaults: see Environment variables.

rustup component add rust-analyzer clippy rustfmt

sea-orm-cli is not needed: runique migration up | down | status runs cargo run on the project's migration crate, whose main calls the CLI of the sea-orm-migration library. See The expected Cargo.toml.