From dfc986972b3e2559762c012b91965a18f69ec028 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20P=C3=A9rex?= Date: Mon, 7 Jul 2025 22:56:34 +0100 Subject: [PATCH] init repo --- README.md | 543 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 543 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ecbd492 --- /dev/null +++ b/README.md @@ -0,0 +1,543 @@ +
+ 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.