init repo
This commit is contained in:
Jesús Pérex
commit
dfc986972b
543
README.md
Normal file
543
README.md
Normal file
@ -0,0 +1,543 @@
|
||||
<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.
|
||||
Loading…
x
Reference in New Issue
Block a user