Rustelo/README.md

A unified, modern, and secure Rust platform to build, deploy, and deliver scalable, high-performance, and reactive web applications with integrated content management, user authentication, multilingual UI, email services, CI/CD pipelines, and comprehensive tooling from development to production.

Note

A comprehensive Rust solution
combining reactive WebAssembly frontends (Leptos) with secure native backends (Axum),
featuring database abstraction (PostgreSQL/SQLite), modular configuration, i18n support, RBAC,
content management, email services, metrics, automated CI/CD pipelines, Docker deployment,
and integrated documentation that scales from 2MB static sites to enterprise applications.

• 🎯 Core Platform Features
• 🚀 Quick Start
  • Option 1: One-Command Setup (Recommended)
  • Option 2: Interactive Configuration
  • Option 3: Manual Setup
• 📦 Optional Features
  • 🔒 TLS (tls)
  • 🔐 Authentication (auth) - Default
  • 📄 Database Content (content-db) - Default
  • 📧 Email System (email) - Default
• 🛠️ Common Configurations
• 🗄️ Database Support
• 🔧 Environment Configuration
• 🏗️ Project Structure
• 📚 API Endpoints
• 🚀 Development
• 🐳 Docker Deployment
• 🔒 Security Features
• 📖 Documentation
• 🧪 Testing
• 📊 Performance Considerations
• 🤝 Contributing
• 📄 License
• 🆘 Support
• 🎯 Use Cases
• 🔄 Migration Guide
• 🌟 What's Next?
• 📚 Documentation System

🚀 Complete Feature Matrix

click to see details

🎯 Core Platform Features

🔧 Development Experience

• WebAssembly Frontend - Rust code compiled to WASM for performance
• Reactive UI System - Fine-grained reactivity with Leptos
• Hot Reload Development - Live code changes without restart
• Unified Type System - Shared types between client and server
• Component-Based Architecture - Reusable UI components
• Just Task Runner - Simple command execution (just dev, just build)

🏗️ Architecture & Framework

• Leptos Frontend - Modern reactive web framework
• Axum Backend - High-performance async web server
• Modular Features - Enable/disable components as needed
• Database Abstraction - Works with PostgreSQL and SQLite
• Memory-Safe by Design - Rust's safety guarantees
• Single Binary Deployment - Self-contained executables from 2MB

🔐 Security Features

Authentication & Authorization

• JWT Token Authentication - Secure token-based auth
• OAuth2 Integration - Google, GitHub, and custom providers
• Two-Factor Authentication (2FA) - TOTP with QR codes
• Password Security - Argon2 hashing, complexity requirements
• Session Management - Secure session handling
• Role-Based Access Control (RBAC) - Fine-grained permissions
• Account Security - Lockout protection, rate limiting

Network & Data Security

• TLS/HTTPS Support - SSL certificate management
• CSRF Protection - Cross-site request forgery prevention
• Security Headers - HSTS, CSP, and other security headers
• Input Validation - Comprehensive input sanitization
• SQL Injection Prevention - Safe database queries
• Data Encryption - AES-GCM encryption for sensitive data
• Audit Logging - Security event tracking

📊 Content Management

Content Creation & Management

• Markdown Support - Rich text with syntax highlighting
• YAML Frontmatter - Structured metadata
• Media Management - Image and video uploads
• Content Versioning - Track content changes
• Draft Mode - Preview before publishing
• Scheduled Publishing - Automated content release
• Content Caching - Performance optimization
• Search & Discovery - Full-text search capabilities

Template & Theming

• Template Engine - Handlebars templates
• Theme System - Customizable appearance
• Responsive Design - Mobile-first approach
• Component Library - Pre-built UI components
• Custom CSS - Tailwind CSS integration
• Multi-language Support - i18n localization

📧 Communication Features

Email System

• Multi-Provider Support - SMTP, SendGrid, Console
• Email Templates - HTML and text templates
• Queue Management - Reliable email delivery
• Contact Forms - Built-in form handling
• Notifications - System and user notifications
• Email Validation - Address verification
• Rate Limiting - Prevent spam and abuse

User Management

• User Registration - Account creation workflow
• Profile Management - User settings and preferences
• Password Reset - Secure password recovery
• Email Verification - Account activation
• User Roles - Admin, moderator, user hierarchies
• Private Content - User-specific content access

📈 Monitoring & Analytics

Metrics & Monitoring

• Prometheus Integration - Industry-standard metrics
• System Metrics - CPU, memory, disk usage
• Application Metrics - Request rates, response times
• Database Metrics - Query performance tracking
• Custom Metrics - Business-specific measurements
• Health Checks - System health monitoring
• Performance Profiling - Code performance analysis

Logging & Debugging

• Structured Logging - JSON formatted logs
• Log Levels - Configurable verbosity
• Error Tracking - Comprehensive error reporting
• Debug Mode - Enhanced development logging
• Audit Trails - User action tracking

🗄️ Database Features

Database Support

• PostgreSQL - Full-featured production database
• SQLite - Lightweight development database
• Database Migrations - Schema versioning
• Query Optimization - Performance tuning
• Connection Pooling - Efficient resource usage
• Backup & Recovery - Data protection

Caching System

• Multi-Level Caching - Memory, Redis, file-based
• Cache Invalidation - Smart cache management
• Performance Optimization - Reduced database load
• Cache Metrics - Hit/miss ratio tracking

🚀 DevOps & Deployment

CI/CD Pipeline

• GitHub Actions - Automated testing and deployment
• Docker Support - Containerized deployment
• Multi-Environment - Dev, staging, production configs
• Automated Testing - Unit, integration, E2E tests
• Security Scanning - Vulnerability detection
• Performance Testing - Load and stress testing

Deployment Options

• Cloud Platforms - AWS, GCP, Azure support
• GitHub Pages - Static site deployment
• Docker Containers - Container orchestration
• Traditional Servers - VPS and dedicated servers
• Kubernetes - Container orchestration
• CDN Integration - Content delivery networks

🛠️ Development Tools

Documentation System

• mdBook Integration - Interactive documentation
• Auto-Generated Docs - API documentation
• Multi-Format Export - PDF, HTML, mobile
• Search Functionality - Full-text documentation search
• Version Control - Documentation versioning
• Deployment Automation - Auto-publish documentation

Configuration Management

• Environment Variables - Flexible configuration
• TOML Configuration - Structured config files
• Feature Flags - Runtime feature control
• Environment-Specific - Dev, staging, prod settings
• Configuration Validation - Error prevention
• Migration Tools - Config upgrade assistance

Build & Tooling

• Cargo Integration - Rust package management
• Asset Pipeline - CSS, JS, image optimization
• Code Generation - Automated code scaffolding
• Lint & Format - Code quality enforcement
• Dependency Management - Automated updates
• Binary Optimization - Size and performance optimization

🌐 Platform Integration

API & Services

• REST API - Full-featured web API
• GraphQL Support - Advanced query capabilities
• WebSocket Support - Real-time communication
• Rate Limiting - API abuse prevention
• API Versioning - Backward compatibility
• OpenAPI/Swagger - API documentation

Third-Party Integration

• OAuth Providers - Social login integration
• Payment Gateways - E-commerce support
• Analytics Services - Google Analytics, etc.
• CDN Services - Content delivery
• Monitoring Services - External monitoring
• Backup Services - Cloud backup integration

📱 User Experience

Interface & Interaction

• Responsive Design - Mobile-first approach
• Progressive Web App - Offline capability
• Accessibility - WCAG compliance
• Dark/Light Mode - User preference themes
• Keyboard Navigation - Full keyboard support
• Touch Gestures - Mobile-friendly interactions

Performance Features

• Code Splitting - Optimized loading
• Lazy Loading - On-demand resource loading
• Service Workers - Offline functionality
• Image Optimization - Automatic compression
• Bundle Analysis - Performance monitoring
• Memory Management - Efficient resource usage

🔧 System Features

Infrastructure

• Load Balancing - Traffic distribution
• Auto-Scaling - Dynamic resource allocation
• Backup Systems - Data protection
• Disaster Recovery - Business continuity
• Monitoring Alerts - Proactive notifications
• Log Aggregation - Centralized logging

Security Infrastructure

• Firewall Integration - Network security
• VPN Support - Secure remote access
• SSL Certificate Management - Automated renewals
• Security Scanning - Vulnerability assessments
• Compliance Tools - GDPR, CCPA compliance
• Penetration Testing - Security validation

---

🎯 Total Feature Count: 100+ Features

Rustelo provides a comprehensive ecosystem with over 100 features across:

• 25+ Security Features
• 20+ Content Management Features
• 15+ DevOps & Deployment Features
• 15+ Database & Caching Features
• 10+ Communication Features
• 10+ Monitoring & Analytics Features
• 15+ Development Tools
• Plus many more...

**This makes Rustelo a complete platform for building modern web applications with enterprise-grade features out of the box! 🚀

🚀 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.