Rustelo/README.md

<div align="center">
  <img src="logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="450" />
</div>

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.