A flexible, feature-rich Rust web application template built with Leptos, Axum, and optional components that you can enable or disable based on your needs.

🚀 Quick Start

New to Rustelo? Check out our Quick Start Guide for a complete walkthrough!

Option 1: One-Command Setup (Recommended)

# Clone and install everything automatically
git clone https://github.com/yourusername/rustelo.git my-app
cd my-app
./scripts/install.sh

# After installation, check your personalized setup report
cat SETUP_COMPLETE.md

Option 2: Interactive Configuration

./scripts/configure-features.sh

Option 3: Manual Setup

# Minimal setup (no optional features)
cargo build --no-default-features

# Full-featured setup (default)
cargo build

# Custom feature combination
cargo build --features "tls,auth"

📦 Optional Features

Rustelo uses a modular architecture where you can choose which components to include:

🔒 TLS (tls)

• What it provides: HTTPS/TLS encryption for secure connections
• Use when: Production deployments, security-sensitive applications
• Dependencies: axum-server, rustls, rustls-pemfile

🔐 Authentication (auth) - Default

• What it provides: Complete authentication system
  • JWT token-based authentication
  • OAuth2 providers (Google, GitHub, etc.)
  • Two-factor authentication (2FA/TOTP)
  • Password hashing with Argon2
  • Session management
  • Database-agnostic: Works with both PostgreSQL and SQLite
• Use when: User accounts, protected content, SaaS applications
• Dependencies: jsonwebtoken, argon2, oauth2, totp-rs, sqlx

📄 Database Content (content-db) - Default

• What it provides: Database-driven content management
  • Markdown rendering with syntax highlighting
  • YAML frontmatter support
  • Content caching
  • Dynamic content loading
  • Database-agnostic: Works with both PostgreSQL and SQLite
• Use when: Blogs, CMS, documentation sites
• Dependencies: pulldown-cmark, syntect, serde_yaml, sqlx

📧 Email System (email) - Default

• What it provides: Complete email functionality
  • Multiple providers (SMTP, SendGrid, Console)
  • Handlebars email templates (HTML & text)
  • Contact and support form components
  • Form validation and error handling
  • Rate limiting and security features
• Use when: Contact forms, notifications, user communications
• Dependencies: lettre, handlebars, urlencoding

🛠️ Common Configurations

Minimal Static Website

cargo build --no-default-features

Perfect for: Marketing sites, landing pages, static documentation

Secure Static Website

cargo build --no-default-features --features tls

Perfect for: Production static sites requiring HTTPS

Authentication-Only App

cargo build --no-default-features --features auth

Perfect for: User portals, SaaS apps, protected content

Content Management System

cargo build --no-default-features --features content-db

Perfect for: Blogs, news sites, documentation

Contact/Communication Site

cargo build --no-default-features --features email

Perfect for: Contact pages, feedback forms, newsletter signups

Full-Featured Application (Default)

cargo build --features "auth,content-db,email"
# or simply: cargo build

Perfect for: Complete web applications, user-generated content

🗄️ Database Support

Rustelo features a database-agnostic architecture that seamlessly works with multiple database backends:

Supported Databases

• PostgreSQL - Full-featured production database
• SQLite - Lightweight, file-based database perfect for development and small deployments

Automatic Database Detection

The application automatically detects your database type from the connection URL:

# PostgreSQL
DATABASE_URL=postgresql://user:pass@localhost/db

# SQLite
DATABASE_URL=sqlite:data/app.db

Migration System

• Separate migration files for each database type
• Automatic database type detection
• Unified migration runner
• Example: 001_initial_setup_postgres.sql and 001_initial_setup_sqlite.sql

Benefits

• Development Flexibility: Use SQLite for local development, PostgreSQL for production
• Deployment Options: Single binary deployments with SQLite, or scalable PostgreSQL clusters
• Testing: Fast SQLite tests, comprehensive PostgreSQL integration tests
• Migration Path: Start with SQLite, migrate to PostgreSQL as you scale

Production-Ready

cargo build --release --features "tls,auth,content-db,email"

Perfect for: Production deployments with all security features

🔧 Environment Configuration

Create a .env file based on your enabled features:

Basic Configuration

SERVER_HOST=127.0.0.1
SERVER_PORT=3030
SERVER_PROTOCOL=http
ENVIRONMENT=DEV
LOG_LEVEL=info

TLS Configuration (if tls feature enabled)

SERVER_PROTOCOL=https
TLS_CERT_PATH=./certs/cert.pem
TLS_KEY_PATH=./certs/key.pem

Database Configuration (if auth or content-db features enabled)

DATABASE_URL=postgres://username:password@localhost:5432/database_name

Authentication Configuration (if auth feature enabled)

JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_EXPIRATION_HOURS=24

# OAuth Providers (optional)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

# 2FA Configuration
TOTP_ISSUER=YourAppName
TOTP_SERVICE_NAME=YourAppName Authentication

Email Configuration (if email feature enabled)

# Email Provider: smtp, sendgrid, or console
EMAIL_PROVIDER=console

# Default sender information
EMAIL_FROM_ADDRESS=noreply@yourapp.com
EMAIL_FROM_NAME=Your App Name

# SMTP Configuration (if using SMTP provider)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_USE_TLS=false
SMTP_USE_STARTTLS=true

# SendGrid Configuration (if using SendGrid provider)
SENDGRID_API_KEY=your-sendgrid-api-key
SENDGRID_ENDPOINT=https://api.sendgrid.com/v3/mail/send

# Email Templates Directory
EMAIL_TEMPLATE_DIR=templates/email

🏗️ Project Structure

template/
├── client/          # Frontend Leptos components
├── server/          # Backend Axum server
├── shared/          # Shared types and utilities
├── content/         # Static content files
├── migrations/      # Database migrations (if using database features)
├── scripts/         # Helper scripts
├── examples/        # Feature usage examples
├── FEATURES.md      # Detailed feature documentation
└── README.md        # This file

📚 API Endpoints

Authentication Endpoints (if auth feature enabled)

• POST /api/auth/login - User login
• POST /api/auth/logout - User logout
• POST /api/auth/register - User registration
• POST /api/auth/refresh - Token refresh
• GET /api/auth/oauth/google - Google OAuth
• GET /api/auth/oauth/github - GitHub OAuth
• POST /api/auth/2fa/setup - 2FA setup
• POST /api/auth/2fa/verify - 2FA verification

Content Endpoints (if content-db feature enabled)

• GET /api/content/pages - List pages
• GET /api/content/page/{slug} - Get page by slug
• GET /api/content/posts - List blog posts
• GET /api/content/post/{slug} - Get post by slug

🚀 Development

Prerequisites

• Rust 1.75+
• Node.js 18+ (for frontend tooling)
• PostgreSQL (if using database features)
• mdBook (for documentation) - cargo install mdbook
• Just (task runner) - cargo install just

Note

: All tools are automatically installed by ./scripts/install.sh. For manual setup, see INSTALL.md.

Quick Setup

# Interactive feature configuration
./scripts/configure-features.sh

# Setup comprehensive documentation
./scripts/docs/setup-docs.sh

# Start development with documentation
./scripts/docs/docs-dev.sh &
cargo leptos serve

# Check your personalized setup report
cat SETUP_COMPLETE.md

Setup Database (if using auth or content-db features)

# Start PostgreSQL
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=password postgres

# Run migrations
sqlx migrate run

Development Server

# Development mode with hot reloading
cargo run

# Or with specific features
cargo run --features "auth,content-db"

# Using cargo-leptos for enhanced development experience
cargo leptos serve

# Using cargo-leptos with custom config
cargo leptos serve -- -c config.dev.toml

Note: If you encounter "Several bin targets found" error with cargo leptos serve, this has been fixed by specifying bin-target = "server" in the workspace configuration.

Documentation Development

# Start documentation development server
./scripts/docs/docs-dev.sh

# Build documentation
./scripts/docs/build-docs.sh

# Sync existing docs into mdBook format
./scripts/docs/build-docs.sh --sync

# Deploy documentation
./scripts/docs/deploy-docs.sh github-pages

Building for Production

# Production build
cargo build --release --features "tls,auth,content-db"

# Docker build
docker build -t rustelo .

🐳 Docker Deployment

Minimal Docker Setup

FROM rust:1.75 as builder
WORKDIR /app
COPY . .
RUN cargo build --release --no-default-features

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/server /usr/local/bin/
EXPOSE 3030
CMD ["server"]

Full-Featured Docker Setup

FROM rust:1.75 as builder
WORKDIR /app
COPY . .
RUN cargo build --release --features "tls,auth,content-db"

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates
COPY --from=builder /app/target/release/server /usr/local/bin/
EXPOSE 443
CMD ["server"]

🔒 Security Features

Always enabled:

• CSRF protection
• Security headers
• Rate limiting
• Input validation
• SQL injection prevention

Optional (with features):

• TLS/HTTPS encryption
• JWT authentication
• OAuth2 integration
• Two-factor authentication
• Password hashing (Argon2)

📖 Documentation

Rustelo comes with comprehensive documentation in multiple formats:

📚 Interactive Documentation (mdBook)

• Complete Guide - Full interactive documentation
• Local Development: ./scripts/docs/docs-dev.sh - Start local docs server
• Build Documentation: ./scripts/docs/build-docs.sh - Build static documentation

📄 Quick References

• FEATURES.md - Detailed feature documentation
• examples/ - Usage examples for different configurations
• migrations/ - Database schema documentation
• docs/ - Technical documentation
• info/ - Implementation details and guides

🔧 Documentation Tools

# Setup complete documentation system
./scripts/docs/setup-docs.sh

# Start development server with live reload
./scripts/docs/docs-dev.sh

# Build documentation
./scripts/docs/build-docs.sh

# Deploy to GitHub Pages
./scripts/docs/deploy-docs.sh github-pages

🧪 Testing

# Test all features
cargo test

# Test specific feature combinations
cargo test --no-default-features
cargo test --features "auth"
cargo test --features "content-db"
cargo test --features "tls,auth,content-db"

📊 Performance Considerations

Binary Size

• Minimal: ~2MB
• With Auth: ~5MB
• With Content-DB: ~4MB
• Full Featured: ~7MB

Memory Usage

• Minimal: ~10MB RAM
• With Database: ~30-40MB RAM
• With TLS: +5MB RAM

Startup Time

• Minimal: ~100ms
• With Database: ~500ms
• With TLS: +200ms

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 🚀 Quick Start: QUICK_START.md - Get started in minutes
• 📋 Setup Report: SETUP_COMPLETE.md - Your personalized setup summary
• 📚 Documentation: Complete Guide
• 🛠️ Installation: INSTALL.md - Detailed installation guide
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Quick Reference: FEATURES.md
• 🔧 Local Docs: ./scripts/docs/docs-dev.sh

🎯 Use Cases

Perfect for:

• SaaS Applications: Full auth + content management
• Marketing Sites: Minimal static setup
• Blogs & CMS: Content-DB focused
• User Portals: Authentication focused
• Documentation Sites: Static or dynamic content
• Enterprise Apps: Full-featured with TLS

Not suitable for:

• High-frequency trading systems
• Real-time gaming backends
• IoT device firmware
• Mobile applications

🔄 Migration Guide

Adding Features to Existing Project

1. Update Cargo.toml features
2. Add required environment variables
3. Run database migrations (if applicable)
4. Update client-side code
5. Test thoroughly

Removing Features

1. Export/backup relevant data
2. Update Cargo.toml features
3. Remove related environment variables
4. Clean up unused code
5. Test reduced functionality

🌟 What's Next?

The modular architecture makes it easy to:

• Add new authentication providers
• Integrate additional databases
• Add caching layers
• Implement WebSocket support
• Add monitoring and metrics
• Scale horizontally

Choose your features, build your application, and scale as needed!

📚 Documentation System

Rustelo includes a comprehensive documentation system built with mdBook:

Features

• 📖 Interactive Documentation: Complete guide with search and navigation
• 🔧 Build Scripts: Automated documentation building and deployment
• 🔄 Content Sync: Automatically sync existing docs into mdBook format
• 🌐 Multiple Deployment Options: GitHub Pages, Netlify, Vercel, AWS S3, Docker
• 📱 Responsive Design: Mobile-friendly documentation
• 🎨 Custom Styling: Branded documentation with custom themes
• 📋 Setup Reports: Personalized installation summaries and quick start guides

Quick Start

# Setup documentation system
./scripts/docs/setup-docs.sh --full

# Start development server
./scripts/docs/docs-dev.sh

# Build and deploy
./scripts/docs/build-docs.sh
./scripts/docs/deploy-docs.sh github-pages

# Check your setup report
cat SETUP_COMPLETE.md

Documentation Structure

• Getting Started: Installation, configuration, first app
• Features: Complete feature documentation with examples
• Database: Database setup and configuration guides
• Development: Development workflow and best practices
• Deployment: Production deployment guides
• API Reference: Complete API documentation
• Security: Security best practices and configuration
• Troubleshooting: Common issues and solutions

The documentation system automatically syncs content from your existing docs/ and info/ directories, making it easy to maintain comprehensive documentation alongside your code.