RUSTELO
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](QUICK_START.md)** for a complete walkthrough! ### Option 1: One-Command Setup (Recommended) ```bash # 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 ```bash ./scripts/configure-features.sh ``` ### Option 3: Manual Setup ```bash # 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 ```bash cargo build --no-default-features ``` Perfect for: Marketing sites, landing pages, static documentation ### Secure Static Website ```bash cargo build --no-default-features --features tls ``` Perfect for: Production static sites requiring HTTPS ### Authentication-Only App ```bash cargo build --no-default-features --features auth ``` Perfect for: User portals, SaaS apps, protected content ### Content Management System ```bash cargo build --no-default-features --features content-db ``` Perfect for: Blogs, news sites, documentation ### Contact/Communication Site ```bash cargo build --no-default-features --features email ``` Perfect for: Contact pages, feedback forms, newsletter signups ### Full-Featured Application (Default) ```bash 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: ```bash # 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 ```bash 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 ```env SERVER_HOST=127.0.0.1 SERVER_PORT=3030 SERVER_PROTOCOL=http ENVIRONMENT=DEV LOG_LEVEL=info ``` ### TLS Configuration (if `tls` feature enabled) ```env SERVER_PROTOCOL=https TLS_CERT_PATH=./certs/cert.pem TLS_KEY_PATH=./certs/key.pem ``` ### Database Configuration (if `auth` or `content-db` features enabled) ```env DATABASE_URL=postgres://username:password@localhost:5432/database_name ``` ### Authentication Configuration (if `auth` feature enabled) ```env 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) ```env # 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](INSTALL.md). ### Quick Setup ```bash # 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) ```bash # Start PostgreSQL docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=password postgres # Run migrations sqlx migrate run ``` ### Development Server ```bash # 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 ```bash # 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 ```bash # Production build cargo build --release --features "tls,auth,content-db" # Docker build docker build -t rustelo . ``` ## ๐Ÿณ Docker Deployment ### Minimal Docker Setup ```dockerfile 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 ```dockerfile 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](https://yourusername.github.io/rustelo)** - 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](FEATURES.md)** - Detailed feature documentation - **[examples/](examples/)** - Usage examples for different configurations - **[migrations/](migrations/)** - Database schema documentation - **[docs/](docs/)** - Technical documentation - **[info/](info/)** - Implementation details and guides ### ๐Ÿ”ง Documentation Tools ```bash # 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 ```bash # 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](LICENSE) file for details. ## ๐Ÿ†˜ Support - **๐Ÿš€ Quick Start**: [QUICK_START.md](QUICK_START.md) - Get started in minutes - **๐Ÿ“‹ Setup Report**: [SETUP_COMPLETE.md](SETUP_COMPLETE.md) - Your personalized setup summary - **๐Ÿ“š Documentation**: [Complete Guide](https://yourusername.github.io/rustelo) - **๐Ÿ› ๏ธ Installation**: [INSTALL.md](INSTALL.md) - Detailed installation guide - **๐Ÿ› Issues**: [GitHub Issues](https://github.com/yourusername/rustelo/issues) - **๐Ÿ’ฌ Discussions**: [GitHub Discussions](https://github.com/yourusername/rustelo/discussions) - **๐Ÿ“– Quick Reference**: [FEATURES.md](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 ```bash # 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.