Adding `roadster` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add roadster

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

roadster = "0.9.0-alpha.3"

The roadster library will be automatically available globally. Read the roadster library documentation.

Back to the crate overview.

Readme

Roadster

A "Batteries Included" web framework for rust designed to get you moving fast 🏎️. Inspired by other fully-featured frameworks such as Rails, Django, Laravel, and Loco.

Features

Built on Tokio's web stack (axum, tower, hyper, tracing). App behavior can be easily extended by taking advantage of all the resources in the tokio ecosystem.
Built-in support for HTTP APIs via Axum (with the http feature) and gRPC APIs via Tonic (with the grpc feature).
Auto-generates an OpenAPI schema for HTTP API routes defined with aide (requires the open-api feature).
Support for running arbitrary long-running services (e.g., an API format not supported out of the box) with minimal boilerplate. Simply provide a FunctionService with your async function and register it in the App#services method.
Provides sensible defaults so you can focus on building your app, but most (all?) of the built-in behavior can be customized or disabled via per-environment configuration files.
Uses #![forbid(unsafe_code)] to ensure all code in Roadster is 100% safe rust.
Provides a CLI for common commands, and allows consumers to provide their own CLI commands using clap (requires the cli feature)
Provides sample JWT extractor for Axum (requires the jwt-ietf and/or jwt-openid features). Also provides a general JWT extractor for Axum that simply puts all claims into a map (available with the jwt feature)
Built-in support for SeaORM, including creating DB connections (requires the db-sea-orm feature)
Built-in support for Diesel, including creating DB connections (requires a subset of the db-diesel-* collection of features, depending on what's needed)
Built-in support for async workers backed by Postgres (via pgmq) or Redis/Sidekiq (via rusty-sidekiq). Requires the worker-pg or worker-sidekiq features, respectively.
Built-in support for sending emails via SMTP (requires the email-smtp feature) or Sendgrid's Mail Send API (requires the email-sendgrid feature)
Structured logs/traces using tokio's tracing crate. Export traces/metrics using OpenTelemetry (requires the otel feature).
Health checks to ensure the app's external dependencies are healthy
Pre-built migrations for common DB tables, e.g. user (requires the db-sea-orm feature)
Support for auto-updating timestamp columns, e.g. updated_at, when updating DB rows (Postgres only currently) ( requires the db-sea-orm feature)

A full list of features and their documentation can also be found in the Roadster book.

Getting started

Start local dependencies

Below are some example commands for running local instances of external dependencies, such as Postgres, Redis, and SMTP servers.

Database

# Replace `example_dev` with your app name, e.g., `myapp_dev`
docker run -d -p 5432:5432 -e POSTGRES_USER=roadster -e POSTGRES_DB=example_dev -e POSTGRES_PASSWORD=roadster postgres:18.0-alpine3.22

Redis instance (for Sidekiq.rs)

docker run -d -p 6379:6379 redis:8.2.2-alpine

SMTP server

Mailpit

docker run -d -p 8025:8025 -p 1025:1025 axllent/mailpit

smtp4dev

docker run -d -p 1080:80 -p 1025:25 rnwood/smtp4dev

maildev

docker run -d -p 1080:1080 -p 1025:1025 maildev/maildev

Create your app

# Using one of our examples for now 
git clone https://github.com/roadster-rs/roadster.git
cd roadster/examples/app-builder

Set the environment (production/development/test)

# Either set it as an environment variable
export ROADSTER__ENVIRONMENT=development
# Or add it to a `.env` file
echo ROADSTER__ENVIRONMENT=development >> .env

Start your app

cargo run

Explore the API

Navigate to http://localhost:3000/api/_docs to explore the app's OpenAPI playground

Add a UI

Currently, Roadster is focused on back-end API development with Rust. We leave it to the consumer to decide how they prefer to add a front-end, e.g., using an established JS/TS framework (React / Next / Vue / Svelte / Solid / etc) or using a Rust front-end framework (Leptos / Yew / Perseus / Sycamore / etc). That said, we do have some examples of how to use Roadster with some these frameworks.

Examples

Framework	Example
Leptos	leptos-ssr

Tracing + OpenTelemetry

Roadster allows reporting traces and metrics using the tracing and opentelemetry-rust integrations. Enable the otel and/or otel-grpc features and provide the URL of your OTLP exporter in order to report the OTEL trace/metric data to your telemetry provider (e.g., Grafana, SigNoz, New Relic, Datadog, etc).

Background/async job queue

Roadster provides built-in support for running async workers using either Postgres (via pgmq) or Redis/Sidekiq (via rusty-sidekiq) as the backing store. See the Background jobs chapter of the book for more details.

Inspecting the Sidekiq state

Sidekiq dashboard

We provide a sample repo to run the sidekiq dashboard locally in a standalone docker container.

git clone https://github.com/roadster-rs/standalone_sidekiq_dashboard.git
cd standalone_sidekiq_dashboard
docker build -t standalone-sidekiq .
# Linux docker commands
# Development
docker run -d --network=host standalone-sidekiq
# Test
docker run -d --network=host -e REDIS_URL='redis://localhost:6380' standalone-sidekiq

# Mac docker commands -- todo: see if there's a command that will work on both mac and linux
# Development
docker run -d -p 9292:9292 -e REDIS_URL=redis://host.docker.internal:6379 standalone-sidekiq
# Test
docker run -d -p 9292:9292 -e REDIS_URL=redis://host.docker.internal:6380 standalone-sidekiq

Redis Insights

You can also inspect the Redis DB directly using RedisInsight.

# Linux docker commands
docker run -d --name redisinsight --network=host -p 5540:5540 redis/redisinsight:latest
# Mac docker commands -- todo: see if there's a command that will work on both mac and linux
# Use `host.docker.internal` as the host domain in redis insight (instead of `127.0.0.1`)
docker run -d --name redisinsight -p 5540:5540 redis/redisinsight:latest

Learning more

Book

The Roadster book provides more details on how to use all of Roadster's features.

Examples

We also provide several examples for how to configure and use Roadster's features. These can be found the examples directory of this repository.

GitHub Discussions

If you have a question not answered in the book or the examples, please open a GitHub Discussion and we'll be happy to help.

Adding roadster library as a dependency

Adding `roadster` library as a dependency