Installation
This guide covers multiple ways to install and set up RustF for development.
Method 1: Using RustF CLI (Recommended)
The easiest way to create a new RustF project is using the CLI tool:
Install the RustF CLI
Prebuilt binary β fastest, no compile (recommended):
# install the binstall helper once, if you don't have it:
cargo install cargo-binstall
# then fetch the prebuilt rustf-cli binary from the GitHub Release:
cargo binstall rustf-cli
From crates.io (compiles from source β needs a few minutes):
cargo install rustf-cli
From source (pre-release / local development):
git clone https://github.com/numerum-tech/rustf.git
cargo install --path rustf/rustf-cli # repo root is the clone dir 'rustf', crate is 'rustf-cli'
Until
rustf-cliis published to crates.io, use the from source method. After publishing,cargo binstall rustf-cliis the quickest path.
Create a New Project
# Create a new project
rustf-cli new project my-app
# Navigate to your project
cd my-app
# Run the server
cargo run
The CLI tool will:
- Set up the correct project structure
- Create necessary directories (controllers, models, views, etc.)
- Generate a basic
main.rswith auto-discovery - Create a sample controller
- Set up configuration files
Method 2: Manual Setup
If you prefer to set up a project manually:
1. Create a New Cargo Project
cargo new my-app
cd my-app
2. Add Dependencies
Edit Cargo.toml:
[package]
name = "my-app"
version = "0.1.0"
edition = "2021"
[dependencies]
rustf = "1.0"
tokio = { version = "1.0", features = ["full"] }
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
log = "0.4"
env_logger = "0.10"
3. Create Project Structure
mkdir -p src/controllers src/models src/modules src/middleware
mkdir -p views/layouts public/css public/js
mkdir -p schemas uploads
4. Create Main Application
Create src/main.rs:
use rustf::prelude::*;
#[tokio::main]
async fn main() -> rustf::Result<()> {
env_logger::init();
let app = RustF::new()
.controllers(auto_controllers!())
.middleware_from(auto_middleware!());
println!("π Server at http://127.0.0.1:8000");
app.start().await
}
5. Create Your First Controller
Create src/controllers/home.rs:
#![allow(unused)]
fn main() {
use rustf::prelude::*;
pub fn install() -> Vec<Route> {
routes![
GET "/" => index,
]
}
async fn index(ctx: &mut Context) -> Result<()> {
ctx.html("<h1>Hello, RustF!</h1>")
}
}
6. Create Configuration
Create config.toml:
[server]
host = "127.0.0.1"
port = 8000
[views]
directory = "views"
cache_enabled = false
Method 3: Using Git Template
You can also use the sample application as a template:
# Clone the repository
git clone https://github.com/numerum-tech/rustf.git
cd rustf/sample-app
# Copy to your project
cp -r . /path/to/your/project
cd /path/to/your/project
# Install dependencies and run
cargo run
Cargo Features
RustF ships its SQL drivers and Redis support as optional, on-by-default features. Out of the box you get everything (PostgreSQL, MySQL, SQLite, and Redis sessions), so most users need no configuration. If you want a leaner build, opt out and enable only what you use.
| Feature | Default | What it enables |
|---|---|---|
database | β | Driverless SQL core (query builder, models, migrations) + decimal |
db-postgres | β | PostgreSQL driver |
db-mysql | β | MySQL / MariaDB driver |
db-sqlite | β | SQLite driver |
redis | β | Redis-backed session storage (the only built-in cross-instance/cluster store) |
embedded-views | β | Compile templates into the binary |
schema | β | YAML schema validation & codegen |
decimal | β | DECIMAL/NUMERIC support via rust_decimal β implied by database, so any db-* feature pulls it in automatically |
cli | β | clap-based CLI argument parsing |
Always compiled (not features): TOML config loading, the auto-discovery macros (
auto_controllers!, β¦), and UUID support are core to the framework and cannot be disabled β there are noconfig/auto-discovery/uuidflags.
Each db-* feature pulls in database automatically and turns on the matching
sqlx driver. A PostgreSQL-only app, for example, can skip compiling the MySQL
and SQLite drivers plus Redis:
[dependencies]
rustf = { version = "1.0", default-features = false, features = [
"embedded-views", "schema",
"db-postgres", # pulls in `database` + `decimal` automatically
] }
Note β clustering:
redisis the only built-in storage that lets multiple RustF instances share session state. If you disable it for a multi-instance deployment, provide your ownSessionStorageimplementation for shared sessions.
Verifying Installation
After installation, verify everything works:
# Build the project
cargo build
# Run tests
cargo test
# Start the server
cargo run
You should see:
π Server at http://127.0.0.1:8000
Visit http://127.0.0.1:8000 in your browser to see your application.
Development Dependencies
For development, you may also want to add:
[dev-dependencies]
tokio-test = "0.4"
tempfile = "3.8"
Troubleshooting
Common Issues
Issue: βcannot find crate rustfβ
- Solution: Make sure youβve added rustf to
Cargo.tomldependencies - If using local development: Use
path = "../rustf"in Cargo.toml - If using published version: Use
version = "1.0.0-rc1"from crates.io
Issue: βproc macro not foundβ
- Solution: Make sure
rustfis a dependency (the auto-discovery macros are re-exported fromrustfand always available β there is no feature to enable) - Bring them into scope with
use rustf::prelude::*;
Issue: βport already in useβ
- Solution: Change the port in
config.tomlor stop the other process - Default port is 8000
Next Steps
Now that you have RustF installed:
- Hello World Tutorial - Build your first application
- Project Structure - Understand the framework layout
- Controllers Guide - Learn about routing and controllers