jesus/Rustelo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: update gitignore and fix content
Some checks failed
CI/CD Pipeline / Test Suite (push) Has been cancelled
Details
CI/CD Pipeline / Security Audit (push) Has been cancelled
Details
CI/CD Pipeline / Build Docker Image (push) Has been cancelled
Details
CI/CD Pipeline / Deploy to Staging (push) Has been cancelled
Details
CI/CD Pipeline / Deploy to Production (push) Has been cancelled
Details
CI/CD Pipeline / Performance Benchmarks (push) Has been cancelled
Details
CI/CD Pipeline / Cleanup (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Jesús Pérez 2026-02-08 20:09:38 +00:00
parent d3a47108af
commit 0aeaa33d9a
Signed by: jesus
GPG Key ID: 9F243E355E0BC939
443 changed files with 36070 additions and 56331 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

176
book/SUMMARY.md
View File

@ -1,176 +0,0 @@
# Summary
[Introduction](./introduction.md)
# Getting Started
- [What is Rustelo?](./getting-started/what-is-rustelo.md)
- [Quick Installation](./getting-started/installation.md)
- [First Run & Setup](./getting-started/first-run.md)
- [First App](./getting-started/first-app.md)
- [Basic Configuration](./getting-started/configuration.md)
# For End Users
## Using the Application
- [User Interface Guide](./users/interface.md)
- [User Registration & Login](./users/authentication.md)
- [Managing Your Profile](./users/profile.md)
- [Content Publishing](./users/content.md)
- [File & Media Management](./users/media.md)
## Features & Functionality
- [Authentication & Security](./users/features/auth.md)
- [Content Management](./users/features/content.md)
- [Email & Notifications](./users/features/email.md)
- [Search & Discovery](./users/features/search.md)
- [Mobile Experience](./users/features/mobile.md)
## Administration
- [Admin Dashboard](./users/admin/dashboard.md)
- [User Management](./users/admin/users.md)
- [Content Moderation](./users/admin/content.md)
- [System Settings](./users/admin/settings.md)
- [Monitoring & Analytics](./users/admin/monitoring.md)
# For Developers
## Development Setup
- [Development Environment](./developers/setup/environment.md)
- [Project Structure](./developers/setup/structure.md)
- [Build System & Tools](./developers/setup/build.md)
- [Development Workflow](./developers/setup/workflow.md)
## Architecture
- [System Overview](./developers/architecture/overview.md)
- [Frontend Architecture](./developers/architecture/frontend.md)
- [Backend Architecture](./developers/architecture/backend.md)
- [Database Design](./developers/architecture/database.md)
- [Security Model](./developers/architecture/security.md)
## Core Components
- [Components Overview](./developers/components/README.md)
- [Authentication System](./developers/components/auth.md)
- [Content Management](./developers/components/content.md)
- [Email System](./developers/components/email.md)
- [Template Engine](./developers/components/templates.md)
- [Configuration System](./developers/components/config.md)
## Feature Development
- [Adding New Features](./developers/features/adding-features.md)
- [Feature Flags & Modules](./developers/features/feature-flags.md)
- [Database Migrations](./developers/features/migrations.md)
- [API Endpoints](./developers/features/api-endpoints.md)
- [Frontend Components](./developers/features/frontend-components.md)
## Brand & Design
- [Logo Usage Guide](./developers/brand/logo-usage.md)
## Testing
- [Testing Strategy](./developers/testing/strategy.md)
- [Unit Testing](./developers/testing/unit.md)
- [Integration Testing](./developers/testing/integration.md)
- [End-to-End Testing](./developers/testing/e2e.md)
- [Performance Testing](./developers/testing/performance.md)
# Configuration
- [Configuration Overview](./configuration/README.md)
- [Environment Variables](./configuration/environment.md)
- [Configuration Files](./configuration/files.md)
- [Features Configuration](./configuration/features.md)
- [Database Configuration](./configuration/database.md)
- [Security Settings](./configuration/security.md)
- [Performance Tuning](./configuration/performance.md)
# Deployment
- [Production Setup](./deployment/production.md)
- [Docker Deployment](./deployment/docker.md)
- [Cloud Platforms](./deployment/cloud.md)
- [SSL/TLS Configuration](./deployment/ssl.md)
- [Monitoring & Logging](./deployment/monitoring.md)
- [Backup & Recovery](./deployment/backup.md)
# API Reference
- [REST API Overview](./api/overview.md)
- [Authentication Endpoints](./api/auth.md)
- [Content Management API](./api/content.md)
- [User Management API](./api/users.md)
- [Email & Notifications API](./api/email.md)
- [Error Handling](./api/errors.md)
- [Rate Limiting](./api/rate-limiting.md)
# Security
- [Security Overview](./security/overview.md)
- [Authentication & Authorization](./security/auth.md)
- [Data Protection](./security/data-protection.md)
- [CSRF & XSS Prevention](./security/web-security.md)
- [TLS & Encryption](./security/encryption.md)
- [Security Best Practices](./security/best-practices.md)
# Performance
- [Performance Overview](./performance/overview.md)
- [Database Optimization](./performance/database.md)
- [Caching Strategies](./performance/caching.md)
- [Frontend Optimization](./performance/frontend.md)
- [Memory Management](./performance/memory.md)
- [Profiling & Monitoring](./performance/monitoring.md)
# Troubleshooting
- [Common Issues](./troubleshooting/common.md)
- [Installation Problems](./troubleshooting/installation.md)
- [Authentication Issues](./troubleshooting/auth.md)
- [Database Problems](./troubleshooting/database.md)
- [Performance Issues](./troubleshooting/performance.md)
- [Build & Development Issues](./troubleshooting/development.md)
- [Getting Help & Support](./troubleshooting/support.md)
# Advanced Topics
- [Custom Features & Extensions](./advanced/extensions.md)
- [Plugin Development](./advanced/plugins.md)
- [Theme Customization](./advanced/themes.md)
- [Integration Examples](./advanced/integrations.md)
- [Scaling & High Availability](./advanced/scaling.md)
- [Migration Strategies](./advanced/migrations.md)
# Contributing
- [Contributing Guidelines](./contributing/guidelines.md)
- [Development Setup](./contributing/setup.md)
- [Code Standards](./contributing/standards.md)
- [Testing Guidelines](./contributing/testing.md)
- [Documentation Guidelines](./contributing/docs.md)
- [Release Process](./contributing/releases.md)
# Reference
- [Configuration Options](./reference/config.md)
- [Environment Variables](./reference/env-vars.md)
- [CLI Commands](./reference/cli.md)
- [Database Schema](./reference/schema.md)
- [Error Codes](./reference/error-codes.md)
- [Feature Matrix](./reference/features.md)
- [System Requirements](./reference/requirements.md)
- [FAQ](./reference/faq.md)
- [Configuration Migration Guide](./reference/config-migration.md)
- [Environment Migration Guide](./reference/env-migration.md)
- [Feature Migration Guide](./reference/feature-migration.md)
---
[Glossary](./glossary.md)

0
book/advanced/custom-content.md
View File

0
book/advanced/custom-features.md
View File

0
book/advanced/extending-auth.md
View File

1
book/advanced/extensions.md
View File

@ -1 +0,0 @@
# Custom Features & Extensions

0
book/advanced/integrations.md
View File

1
book/advanced/migrations.md
View File

@ -1 +0,0 @@
# Migration Strategies

0
book/advanced/performance-tuning.md
View File

1
book/advanced/plugins.md
View File

@ -1 +0,0 @@
# Plugin Development

1
book/advanced/scaling.md
View File

@ -1 +0,0 @@
# Scaling & High Availability

1
book/advanced/themes.md
View File

@ -1 +0,0 @@
# Theme Customization

0
book/api/auth.md
View File

0
book/api/content.md
View File

1
book/api/email.md
View File

@ -1 +0,0 @@
# Email & Notifications API

0
book/api/errors.md
View File

0
book/api/overview.md
View File

0
book/api/rate-limiting.md
View File

1
book/api/users.md
View File

@ -1 +0,0 @@
# User Management API

0
book/appendices/cli-commands.md
View File

51
book/appendices/env-variables.md
View File

@ -1,51 +0,0 @@
# Environment Variables Reference
This document lists all environment variables used by Rustelo.
## Core Variables
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `SERVER_HOST` | Server bind address | `127.0.0.1` | No |
| `SERVER_PORT` | Server port | `3030` | No |
| `SERVER_PROTOCOL` | Protocol (http/https) | `http` | No |
| `ENVIRONMENT` | Environment (DEV/PROD) | `DEV` | No |
| `LOG_LEVEL` | Log level | `info` | No |
## Database Variables (auth, content-db features)
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `DATABASE_URL` | Database connection URL | - | Yes |
| `DATABASE_MAX_CONNECTIONS` | Maximum connections | `10` | No |
| `DATABASE_MIN_CONNECTIONS` | Minimum connections | `1` | No |
## Authentication Variables (auth feature)
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `JWT_SECRET` | JWT signing secret | - | Yes |
| `JWT_EXPIRATION_HOURS` | JWT expiration | `24` | No |
| `GOOGLE_CLIENT_ID` | Google OAuth client ID | - | No |
| `GOOGLE_CLIENT_SECRET` | Google OAuth secret | - | No |
| `GITHUB_CLIENT_ID` | GitHub OAuth client ID | - | No |
| `GITHUB_CLIENT_SECRET` | GitHub OAuth secret | - | No |
## TLS Variables (tls feature)
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `TLS_CERT_PATH` | TLS certificate path | - | Yes |
| `TLS_KEY_PATH` | TLS private key path | - | Yes |
## Email Variables (email feature)
| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `EMAIL_PROVIDER` | Email provider | `console` | No |
| `EMAIL_FROM_ADDRESS` | Default from address | - | Yes |
| `EMAIL_FROM_NAME` | Default from name | - | No |
| `SMTP_HOST` | SMTP server host | - | Conditional |
| `SMTP_PORT` | SMTP server port | `587` | Conditional |
| `SMTP_USERNAME` | SMTP username | - | Conditional |
| `SMTP_PASSWORD` | SMTP password | - | Conditional |

0
book/appendices/faq.md
View File

38
book/appendices/feature-matrix.md
View File

@ -1,38 +0,0 @@
# Feature Matrix
This matrix shows which features are available in different configurations.
| Feature | Minimal | Auth | Content | Email | TLS | Full |
|---------|---------|------|---------|-------|-----|------|
| Static Files | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Routing | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Security Headers | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| JWT Auth | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ |
| OAuth2 | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ |
| 2FA/TOTP | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ |
| Database Content | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ |
| Markdown Rendering | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ |
| Email System | ❌ | ❌ | ❌ | ✅ | ❌ | ✅ |
| HTTPS/TLS | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ |
## Build Commands
```bash
# Minimal
cargo build --no-default-features
# Authentication only
cargo build --no-default-features --features "auth"
# Content management only
cargo build --no-default-features --features "content-db"
# Email only
cargo build --no-default-features --features "email"
# TLS only
cargo build --no-default-features --features "tls"
# Full featured
cargo build --features "auth,content-db,email,tls"
```

0
book/appendices/migration-guide.md
View File

424
book/configuration/README.md
View File

@ -1,424 +0,0 @@
# Rustelo Configuration
Welcome to the Rustelo Configuration documentation! This comprehensive guide covers all aspects of configuring your Rustelo application for different environments and use cases.
## 📋 Configuration Overview
Rustelo uses a powerful, modular configuration system that allows you to:
- **Environment-specific configurations** - Different settings for dev, staging, production
- **Feature-based configuration** - Enable/disable features as needed
- **Secure secret management** - Environment variables for sensitive data
- **Modular composition** - Build configurations from reusable components
- **Runtime validation** - Ensure configurations are valid before startup
## 🎯 Quick Start
### Basic Configuration
```bash
# Build development configuration
./config/scripts/build-config.sh dev
# Build production configuration
./config/scripts/build-config.sh prod config.prod.toml
# View configuration status
./config/scripts/debug-manage.sh status
```
### Environment Variables
```bash
# Create .env file
cat > .env << EOF
DATABASE_URL=sqlite//:app.db
SESSION_SECRET=your-session-secret
JWT_SECRET=your-jwt-secret
EOF
# Load environment
source .env
```
## 📖 Configuration Guides
### Core Configuration
- **[Database Configuration](./database.md)** - Database connections, migrations, and pooling
- **[Environment Variables](./environment.md)** - Managing secrets and environment-specific settings
- **[Security Configuration](./security.md)** - Authentication, authorization, and security settings
- **[Performance Configuration](./performance.md)** - Optimization and performance tuning
### Advanced Configuration
- **[Feature Configuration](./features.md)** - Enable/disable application features
- **[Configuration Files](./files.md)** - Understanding configuration file structure
- **[Configuration Files](./files.md)** - Understanding configuration file structure
- **[Security Configuration](./security.md)** - Security settings and best practices
## 🏗️ Configuration Architecture
### File Structure
```
config/
├── base/ # Base configurations
│ ├── dev.toml # Development base
│ ├── prod.toml # Production base
│ └── example.toml # Example/documentation
├── features/ # Feature-specific configs
│ ├── auth/ # Authentication features
│ ├── content/ # Content management
│ ├── email/ # Email system
│ ├── metrics/ # Monitoring & metrics
│ └── tls/ # TLS/SSL configuration
└── scripts/ # Configuration tools
├── build-config.sh # Build configurations
├── debug-manage.sh # Debug and management
└── validate-config.sh # Validation tools
```
### Configuration Layers
1. **Base Configuration** - Core application settings
2. **Feature Configuration** - Feature-specific settings
3. **Environment Variables** - Runtime secrets and overrides
4. **Command Line Arguments** - Runtime parameter overrides
## 🔧 Configuration Types
### Application Configuration
```toml
[app]
name = "My Rustelo App"
version = "1.0.0"
environment = "development"
debug = true
[server]
host = "127.0.0.1"
port = 3030
workers = 4
```
### Database Configuration
```toml
[database]
url = "${DATABASE_URL}"
max_connections = 10
min_connections = 2
connect_timeout = 30
idle_timeout = 300
```
### Feature Configuration
```toml
[features]
auth = true
content_db = true
email = false
metrics = true
tls = false
```
### Security Configuration
```toml
[security]
session_secret = "${SESSION_SECRET}"
jwt_secret = "${JWT_SECRET}"
csrf_protection = true
rate_limiting = true
secure_cookies = true
```
## 🌍 Environment Management
### Development Environment
```bash
# Development configuration
DATABASE_URL=sqlite//:dev.db
SESSION_SECRET=dev-session-secret
LOG_LEVEL=debug
ENABLE_HOT_RELOAD=true
```
### Production Environment
```bash
# Production configuration
DATABASE_URL=postgresql://user:pass@host:5432/db
SESSION_SECRET=secure-random-secret
LOG_LEVEL=info
ENABLE_HOT_RELOAD=false
DOMAIN=myapp.com
```
### Staging Environment
```bash
# Staging configuration
DATABASE_URL=postgresql://user:pass@staging-host:5432/db
SESSION_SECRET=staging-secret
LOG_LEVEL=info
ENABLE_DEBUG=false
```
## 🔐 Secret Management
### Environment Variables
```bash
# Required secrets
export SESSION_SECRET=$(openssl rand -base64 32)
export JWT_SECRET=$(openssl rand -base64 32)
export DATABASE_URL="postgresql://user:pass@host:5432/db"
# Optional secrets
export SMTP_PASSWORD="your-smtp-password"
export OAUTH_CLIENT_SECRET="your-oauth-secret"
```
### Secret Management Tools
```bash
# Generate secure secrets
./config/scripts/generate-secrets.sh
# Encrypt/decrypt configuration
./config/scripts/encrypt-config.sh
./config/scripts/decrypt-config.sh
# Validate secrets
./config/scripts/validate-secrets.sh
```
## 🎛️ Feature Management
### Enabling Features
```toml
[features]
# Authentication system
auth = true
# Content management
content_db = true
# Email functionality
email = true
# Monitoring and metrics
metrics = true
# TLS/SSL support
tls = true
```
### Feature Dependencies
```toml
[features.auth]
enabled = true
dependencies = ["crypto", "database"]
[features.content_db]
enabled = true
dependencies = ["database", "auth"]
[features.email]
enabled = false
dependencies = ["auth"]
```
## 🚀 Configuration Best Practices
### Development Best Practices
- Use SQLite for development databases
- Enable debug logging
- Use relaxed security settings
- Enable hot reloading
- Use local file storage
### Production Best Practices
- Use PostgreSQL for production databases
- Enable minimal logging
- Use strict security settings
- Disable debug features
- Use cloud storage services
### Security Best Practices
- Never commit secrets to version control
- Use environment variables for sensitive data
- Rotate secrets regularly
- Use strong encryption keys
- Enable HTTPS in production
## 📊 Configuration Validation
### Validation Scripts
```bash
# Validate current configuration
./config/scripts/validate-config.sh
# Validate specific environment
./config/scripts/validate-config.sh prod
# Check configuration completeness
./config/scripts/check-config.sh
```
### Schema Validation
```toml
[validation]
strict_mode = true
required_fields = ["database.url", "security.session_secret"]
allowed_environments = ["dev", "staging", "prod"]
```
## 🔄 Configuration Updates
### Runtime Updates
```bash
# Reload configuration (if supported)
kill -HUP $(pidof rustelo-server)
# Update feature flags
./config/scripts/update-features.sh --enable email
# Apply configuration changes
./config/scripts/apply-config.sh
```
### Configuration Deployment
```bash
# Deploy configuration to staging
./config/scripts/deploy-config.sh staging
# Deploy configuration to production
./config/scripts/deploy-config.sh prod
# Rollback configuration
./config/scripts/rollback-config.sh
```
## 🧪 Testing Configuration
### Configuration Tests
```bash
# Test configuration validity
just config-test
# Test feature configurations
just config-test-features
# Test environment configurations
just config-test-env prod
```
### Integration Tests
```bash
# Test configuration integration
cargo test --test config_integration
# Test feature integration
cargo test --test feature_integration
```
## 🔍 Troubleshooting
### Common Issues
#### Configuration Not Found
```bash
# Check configuration file exists
ls -la config.toml
# Rebuild configuration
./config/scripts/build-config.sh dev
```
#### Environment Variables Missing
```bash
# Check environment variables
env | grep -E "(DATABASE_URL|SESSION_SECRET|JWT_SECRET)"
# Load environment file
source .env
```
#### Feature Configuration Conflicts
```bash
# Check feature dependencies
./config/scripts/debug-manage.sh check-features
# Resolve conflicts
./config/scripts/resolve-conflicts.sh
```
### Debug Tools
```bash
# Debug configuration
./config/scripts/debug-manage.sh debug
# Show configuration tree
./config/scripts/debug-manage.sh tree
# Validate configuration
./config/scripts/debug-manage.sh validate
```
## 📚 Configuration Examples
### Minimal Configuration
```toml
[app]
name = "My App"
environment = "development"
[database]
url = "sqlite://app.db"
[features]
auth = true
```
### Full-Featured Configuration
```toml
[app]
name = "Production App"
environment = "production"
debug = false
[server]
host = "0.0.0.0"
port = 443
workers = 8
[database]
url = "${DATABASE_URL}"
max_connections = 20
ssl_mode = "require"
[features]
auth = true
content_db = true
email = true
metrics = true
tls = true
[security]
session_secret = "${SESSION_SECRET}"
jwt_secret = "${JWT_SECRET}"
csrf_protection = true
rate_limiting = true
secure_cookies = true
```
## 🎯 Next Steps
1. **[Database Configuration](./database.md)** - Set up your database
2. **[Environment Variables](./environment.md)** - Configure environment-specific settings
3. **[Security Configuration](./security.md)** - Secure your application
4. **[Feature Configuration](./features.md)** - Enable the features you need
5. **[Performance Configuration](./performance.md)** - Optimize for production
## 🆘 Getting Help
- **[Common Issues](../troubleshooting/common.md)** - Solutions to common problems
- **[Configuration Files Guide](./files.md)** - Understanding configuration structure
- **[Environment Guide](./environment.md)** - Environment variable management
- **Community Support** - Discord, GitHub Issues, Stack Overflow
---
**Master your Rustelo configuration!** 🦀⚙️

343
book/configuration/database.md
View File

@ -1,343 +0,0 @@
# Database Configuration
<div align="center">
<img src="../../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
</div>
This guide covers how to configure and use databases in RUSTELO. The application supports both **PostgreSQL** and **SQLite** databases through SQLx's unified interface, with automatic database type detection based on the connection URL.
## Quick Start
### SQLite (Recommended for Development)
```toml
[database]
url = "sqlite://database.db"
```
### PostgreSQL (Recommended for Production)
```toml
[database]
url = "postgresql://username:password@localhost:5432/database_name"
```
## Database URL Formats
### SQLite URLs
- `sqlite://database.db` - Relative path to database file
- `sqlite:///path/to/database.db` - Absolute path to database file
- `sqlite::memory:` - In-memory database (testing only)
### PostgreSQL URLs
- `postgresql://user:password@host:port/database`
- `postgres://user:password@host:port/database`
## Environment Variables
You can override the database URL using environment variables:
```bash
export DATABASE_URL="sqlite//:my_database.db"
# or
export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
```
## Database-Specific Features
### SQLite
- **Pros:**
- Zero configuration setup
- Single file database
- Perfect for development and testing
- No separate server process required
- ACID compliant
- **Cons:**
- Limited concurrent writes
- No network access
- Fewer advanced features
- File-based storage
### PostgreSQL
- **Pros:**
- Full ACID compliance
- Excellent concurrent access
- Advanced features (JSONB, arrays, etc.)
- Network accessible
- Production-ready scalability
- **Cons:**
- Requires PostgreSQL server
- More complex setup
- Resource overhead
## Configuration Examples
### Development Configuration
```toml
# config.dev.toml
[database]
url = "sqlite://dev_database.db"
max_connections = 5
min_connections = 1
connect_timeout = 30
idle_timeout = 300
max_lifetime = 1800
```
### Production Configuration
```toml
# config.prod.toml
[database]
url = "postgresql://prod_user:${DATABASE_PASSWORD}@db.example.com:5432/prod_database"
max_connections = 20
min_connections = 5
connect_timeout = 30
idle_timeout = 600
max_lifetime = 3600
```
## Connection Pool Settings
| Setting | Description | SQLite | PostgreSQL |
|---------|-------------|--------|------------|
| `max_connections` | Maximum pool size | 1 (recommended) | 10-50 |
| `min_connections` | Minimum pool size | 1 | 1-5 |
| `connect_timeout` | Connection timeout (seconds) | 30 | 30 |
| `idle_timeout` | Idle connection timeout (seconds) | 300 | 600 |
| `max_lifetime` | Maximum connection lifetime (seconds) | 1800 | 3600 |
## Database Setup
### SQLite Setup
No setup required! The database file will be created automatically when the application starts.
### PostgreSQL Setup
#### Using Docker
```bash
# Start PostgreSQL container
docker run -d \
--name postgres \
-e POSTGRES_PASSWORD=password \
-e POSTGRES_DB=myapp \
-p 5432:5432 \
postgres:15
# Connect to database
docker exec -it postgres psql -U postgres -d myapp
```
#### Using Local Installation
**macOS (Homebrew):**
```bash
brew install postgresql
brew services start postgresql
createdb myapp
```
**Ubuntu/Debian:**
```bash
sudo apt-get install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo -u postgres createdb myapp
```
## Migration Support
The application automatically creates the necessary tables for both database types:
### SQLite Tables
- Uses `TEXT` for IDs (UUID format)
- Uses `DATETIME` for timestamps
- Uses `TEXT` for JSON storage
- Uses `BOOLEAN` for boolean values
### PostgreSQL Tables
- Uses `UUID` for IDs with `gen_random_uuid()`
- Uses `TIMESTAMPTZ` for timestamps
- Uses `JSONB` for JSON storage
- Uses `BOOLEAN` for boolean values
## Switching Between Databases
You can switch between databases by simply changing the `DATABASE_URL`:
```bash
# Switch to SQLite
export DATABASE_URL="sqlite://database.db"
# Switch to PostgreSQL
export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
```
The application will automatically:
1. Detect the database type
2. Use appropriate SQL syntax
3. Create compatible table schemas
4. Handle data type differences
## Performance Considerations
### SQLite
- **Best for:**
- Single-user applications
- Development and testing
- Small to medium datasets
- Read-heavy workloads
- **Optimization tips:**
- Use WAL mode: `PRAGMA journal_mode=WAL`
- Set appropriate timeout: `PRAGMA busy_timeout=5000`
- Use transactions for bulk operations
### PostgreSQL
- **Best for:**
- Multi-user applications
- Production environments
- Large datasets
- High concurrency requirements
- **Optimization tips:**
- Configure appropriate connection pool size
- Use indexes on frequently queried columns
- Monitor and tune PostgreSQL configuration
- Use connection pooling (PgBouncer) for high traffic
## Troubleshooting
### Common SQLite Issues
- **Database locked**: Check for long-running transactions
- **File permissions**: Ensure write access to database file and directory
- **Disk space**: Verify sufficient disk space for database growth
### Common PostgreSQL Issues
- **Connection refused**: Check PostgreSQL server status
- **Authentication failed**: Verify username/password and pg_hba.conf
- **Too many connections**: Adjust max_connections or use connection pooling
### Debug Connection Issues
```bash
# Test SQLite connection
sqlite3 database.db "SELECT 1;"
# Test PostgreSQL connection
psql "postgresql://user:pass@localhost:5432/mydb" -c "SELECT 1;"
```
## Environment-Specific Configuration
### Development
```bash
# .env.development
DATABASE_URL=sqlite://dev_database.db
```
### Testing
```bash
# .env.test
DATABASE_URL=sqlite::memory:
```
### Production
```bash
# .env.production
DATABASE_URL=postgresql://user:${DATABASE_PASSWORD}@db.internal:5432/prod_db
```
## Security Considerations
### SQLite Security
- Protect database file permissions (600 or 640)
- Backup database files securely
- Consider encryption for sensitive data
### PostgreSQL Security
- Use strong passwords
- Enable SSL/TLS connections
- Restrict network access
- Regular security updates
- Use connection pooling with authentication
## Backup and Recovery
### SQLite Backup
```bash
# Simple file copy
cp database.db database_backup.db
# Using SQLite backup command
sqlite3 database.db ".backup database_backup.db"
```
### PostgreSQL Backup
```bash
# Database dump
pg_dump myapp > myapp_backup.sql
# Restore from dump
psql myapp < myapp_backup.sql
```
## Monitoring and Maintenance
### SQLite Maintenance
```sql
-- Analyze database
ANALYZE;
-- Vacuum database
VACUUM;
-- Check integrity
PRAGMA integrity_check;
```
### PostgreSQL Maintenance
```sql
-- Analyze tables
ANALYZE;
-- Vacuum tables
VACUUM;
-- Check database size
SELECT pg_size_pretty(pg_database_size('myapp'));
```
## Best Practices
1. **Use environment variables** for database URLs in production
2. **Configure appropriate connection pools** based on your workload
3. **Monitor database performance** and adjust settings as needed
4. **Regular backups** are essential for production databases
5. **Test migrations** on both database types if supporting both
6. **Use transactions** for data consistency
7. **Index frequently queried columns** for better performance
8. **Monitor connection pool usage** to prevent exhaustion
## Feature Compatibility Matrix
| Feature | SQLite | PostgreSQL |
|---------|--------|------------|
| ACID Transactions | ✅ | ✅ |
| Concurrent Reads | ✅ | ✅ |
| Concurrent Writes | ⚠️ Limited | ✅ |
| JSON Support | ✅ (TEXT) | ✅ (JSONB) |
| Full-text Search | ✅ (FTS) | ✅ (Built-in) |
| Network Access | ❌ | ✅ |
| Replication | ❌ | ✅ |
| Partitioning | ❌ | ✅ |
| Custom Functions | ✅ | ✅ |
| Triggers | ✅ | ✅ |
| Views | ✅ | ✅ |
| Stored Procedures | ❌ | ✅ |
## Next Steps
- [Database Migrations](../developers/features/migrations.md)
- [Performance Optimization](../performance/database.md)
- [Security Best Practices](../security/data-protection.md)
- [Backup Strategies](../deployment/backup.md)
This guide should help you choose and configure the right database for your needs. Both options are fully supported and the application will work seamlessly with either choice.

543
book/configuration/environment.md
View File

@ -1,543 +0,0 @@
# Environment Variables
Rustelo uses environment variables to configure sensitive settings, deployment-specific values, and runtime parameters. This approach ensures that secrets are kept separate from the codebase while allowing flexible configuration across different environments.
## Overview
Environment variables in Rustelo are used for:
- **Sensitive Information**: Database credentials, API keys, secrets
- **Environment-Specific Settings**: URLs, domains, feature flags
- **Runtime Configuration**: Debug modes, logging levels, performance tuning
- **Third-Party Integration**: External service configuration
## Variable Categories
### Core System Variables
#### `RUSTELO_ENV`
- **Description**: Application environment
- **Values**: `development`, `production`, `staging`, `test`
- **Default**: `development`
- **Example**: `RUSTELO_ENV=production`
#### `RUSTELO_CONFIG_FILE`
- **Description**: Path to configuration file
- **Default**: `config.toml`
- **Example**: `RUSTELO_CONFIG_FILE=/etc/rustelo/config.prod.toml`
#### `RUSTELO_LOG_LEVEL`
- **Description**: Global log level override
- **Values**: `error`, `warn`, `info`, `debug`, `trace`
- **Default**: From config file
- **Example**: `RUSTELO_LOG_LEVEL=info`
### Database Configuration
#### `DATABASE_URL`
- **Description**: Database connection string
- **Required**: Yes (production)
- **Format**: `postgresql://user:password@host:port/database`
- **Example**: `DATABASE_URL=postgresql://rustelo:password@localhost:5432/rustelo_prod`
#### `DATABASE_MAX_CONNECTIONS`
- **Description**: Maximum database connections
- **Default**: From config file
- **Example**: `DATABASE_MAX_CONNECTIONS=20`
#### `DATABASE_SSL_MODE`
- **Description**: Database SSL mode
- **Values**: `disable`, `allow`, `prefer`, `require`
- **Default**: `prefer`
- **Example**: `DATABASE_SSL_MODE=require`
### Authentication & Security
#### `SESSION_SECRET`
- **Description**: Session encryption secret
- **Required**: Yes
- **Min Length**: 32 characters
- **Example**: `SESSION_SECRET=your-very-long-and-secure-session-secret-here`
#### `JWT_SECRET`
- **Description**: JWT signing secret
- **Required**: Yes (if JWT enabled)
- **Min Length**: 32 characters
- **Example**: `JWT_SECRET=your-jwt-signing-secret-here`
#### `ENCRYPTION_KEY`
- **Description**: Application-level encryption key
- **Required**: Yes (if encryption enabled)
- **Length**: 32 bytes (base64 encoded)
- **Example**: `ENCRYPTION_KEY=your-base64-encoded-encryption-key`
#### `CSRF_SECRET`
- **Description**: CSRF protection secret
- **Required**: No (auto-generated if not provided)
- **Example**: `CSRF_SECRET=your-csrf-secret-here`
### Email Configuration
#### `SMTP_HOST`
- **Description**: SMTP server hostname
- **Required**: Yes (if email enabled)
- **Example**: `SMTP_HOST=smtp.gmail.com`
#### `SMTP_PORT`
- **Description**: SMTP server port
- **Default**: `587`
- **Example**: `SMTP_PORT=587`
#### `SMTP_USERNAME`
- **Description**: SMTP authentication username
- **Required**: Yes (if SMTP auth enabled)
- **Example**: `SMTP_USERNAME=your-app@gmail.com`
#### `SMTP_PASSWORD`
- **Description**: SMTP authentication password
- **Required**: Yes (if SMTP auth enabled)
- **Example**: `SMTP_PASSWORD=your-app-password`
#### `FROM_EMAIL`
- **Description**: Default sender email address
- **Required**: Yes (if email enabled)
- **Example**: `FROM_EMAIL=noreply@yourapp.com`
#### `FROM_NAME`
- **Description**: Default sender name
- **Default**: Application name
- **Example**: `FROM_NAME=Your App Name`
### Web Server Configuration
#### `RUSTELO_HOST`
- **Description**: Server bind address
- **Default**: `127.0.0.1` (dev), `0.0.0.0` (prod)
- **Example**: `RUSTELO_HOST=0.0.0.0`
#### `RUSTELO_PORT`
- **Description**: Server port
- **Default**: `3030`
- **Example**: `RUSTELO_PORT=8080`
#### `RUSTELO_WORKERS`
- **Description**: Number of worker threads
- **Default**: CPU core count
- **Example**: `RUSTELO_WORKERS=4`
#### `DOMAIN`
- **Description**: Application domain for cookies and CORS
- **Required**: Yes (production)
- **Example**: `DOMAIN=yourapp.com`
#### `FRONTEND_URL`
- **Description**: Frontend application URL
- **Required**: Yes (if separate frontend)
- **Example**: `FRONTEND_URL=https://app.yourapp.com`
### Redis Configuration
#### `REDIS_URL`
- **Description**: Redis connection string
- **Required**: Yes (if Redis enabled)
- **Example**: `REDIS_URL=redis://localhost:6379`
#### `REDIS_PASSWORD`
- **Description**: Redis authentication password
- **Required**: No (if Redis auth disabled)
- **Example**: `REDIS_PASSWORD=your-redis-password`
#### `REDIS_DATABASE`
- **Description**: Redis database number
- **Default**: `0`
- **Example**: `REDIS_DATABASE=1`
### SSL/TLS Configuration
#### `TLS_CERT_FILE`
- **Description**: Path to TLS certificate file
- **Required**: Yes (if HTTPS enabled)
- **Example**: `TLS_CERT_FILE=/etc/ssl/certs/yourapp.crt`
#### `TLS_KEY_FILE`
- **Description**: Path to TLS private key file
- **Required**: Yes (if HTTPS enabled)
- **Example**: `TLS_KEY_FILE=/etc/ssl/private/yourapp.key`
#### `TLS_CA_FILE`
- **Description**: Path to TLS CA certificate file
- **Required**: No
- **Example**: `TLS_CA_FILE=/etc/ssl/certs/ca-certificates.crt`
### External Services
#### `OAUTH_GOOGLE_CLIENT_ID`
- **Description**: Google OAuth client ID
- **Required**: Yes (if Google OAuth enabled)
- **Example**: `OAUTH_GOOGLE_CLIENT_ID=your-google-client-id`
#### `OAUTH_GOOGLE_CLIENT_SECRET`
- **Description**: Google OAuth client secret
- **Required**: Yes (if Google OAuth enabled)
- **Example**: `OAUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret`
#### `OAUTH_GITHUB_CLIENT_ID`
- **Description**: GitHub OAuth client ID
- **Required**: Yes (if GitHub OAuth enabled)
- **Example**: `OAUTH_GITHUB_CLIENT_ID=your-github-client-id`
#### `OAUTH_GITHUB_CLIENT_SECRET`
- **Description**: GitHub OAuth client secret
- **Required**: Yes (if GitHub OAuth enabled)
- **Example**: `OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret`
### Monitoring & Observability
#### `PROMETHEUS_ENDPOINT`
- **Description**: Prometheus metrics endpoint
- **Default**: `/metrics`
- **Example**: `PROMETHEUS_ENDPOINT=/prometheus`
#### `JAEGER_ENDPOINT`
- **Description**: Jaeger tracing endpoint
- **Required**: No
- **Example**: `JAEGER_ENDPOINT=http://localhost:14268/api/traces`
#### `SENTRY_DSN`
- **Description**: Sentry error reporting DSN
- **Required**: No
- **Example**: `SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id`
### Development & Debug
#### `RUST_LOG`
- **Description**: Rust logging configuration
- **Default**: `info`
- **Example**: `RUST_LOG=rustelo=debug,sqlx=info`
#### `RUST_BACKTRACE`
- **Description**: Enable Rust backtraces
- **Values**: `0`, `1`, `full`
- **Default**: `0`
- **Example**: `RUST_BACKTRACE=1`
#### `RUSTELO_DEBUG`
- **Description**: Enable debug mode
- **Values**: `true`, `false`
- **Default**: `false`
- **Example**: `RUSTELO_DEBUG=true`
#### `RUSTELO_MOCK_EXTERNAL`
- **Description**: Mock external services
- **Values**: `true`, `false`
- **Default**: `false`
- **Example**: `RUSTELO_MOCK_EXTERNAL=true`
## Environment-Specific Configuration
### Development Environment
```bash
# Core settings
RUSTELO_ENV=development
RUSTELO_LOG_LEVEL=debug
RUSTELO_DEBUG=true
# Database
DATABASE_URL=sqlite//:dev_database.db
# Authentication
SESSION_SECRET=dev-session-secret-change-in-production
JWT_SECRET=dev-jwt-secret-change-in-production
# Email (console output)
SMTP_HOST=localhost
SMTP_PORT=1025
FROM_EMAIL=dev@localhost
# Features
RUSTELO_MOCK_EXTERNAL=true
```
### Production Environment
```bash
# Core settings
RUSTELO_ENV=production
RUSTELO_LOG_LEVEL=info
RUSTELO_DEBUG=false
# Server
RUSTELO_HOST=0.0.0.0
RUSTELO_PORT=443
DOMAIN=yourapp.com
FRONTEND_URL=https://yourapp.com
# Database
DATABASE_URL=postgresql://rustelo:password@db-server:5432/rustelo_prod
DATABASE_MAX_CONNECTIONS=20
DATABASE_SSL_MODE=require
# Authentication
SESSION_SECRET=your-production-session-secret-64-chars-long
JWT_SECRET=your-production-jwt-secret-64-chars-long
ENCRYPTION_KEY=your-base64-encoded-encryption-key
# Email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-app@gmail.com
SMTP_PASSWORD=your-app-password
FROM_EMAIL=noreply@yourapp.com
FROM_NAME=Your App
# Redis
REDIS_URL=redis://redis-server:6379
REDIS_PASSWORD=your-redis-password
# TLS
TLS_CERT_FILE=/etc/ssl/certs/yourapp.crt
TLS_KEY_FILE=/etc/ssl/private/yourapp.key
# OAuth
OAUTH_GOOGLE_CLIENT_ID=your-google-client-id
OAUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret
# Monitoring
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
```
### Staging Environment
```bash
# Core settings
RUSTELO_ENV=staging
RUSTELO_LOG_LEVEL=info
RUSTELO_DEBUG=true
# Server
RUSTELO_HOST=0.0.0.0
RUSTELO_PORT=443
DOMAIN=staging.yourapp.com
FRONTEND_URL=https://staging.yourapp.com
# Database
DATABASE_URL=postgresql://rustelo:password@staging-db:5432/rustelo_staging
DATABASE_MAX_CONNECTIONS=10
DATABASE_SSL_MODE=prefer
# Authentication (use staging secrets)
SESSION_SECRET=staging-session-secret-64-chars-long
JWT_SECRET=staging-jwt-secret-64-chars-long
# Email (test configuration)
SMTP_HOST=smtp.mailtrap.io
SMTP_PORT=2525
SMTP_USERNAME=your-mailtrap-username
SMTP_PASSWORD=your-mailtrap-password
FROM_EMAIL=staging@yourapp.com
```
## Environment File Management
### `.env` Files
Create environment-specific `.env` files:
```bash
# .env.development
RUSTELO_ENV=development
DATABASE_URL=sqlite:dev_database.db
SESSION_SECRET=dev-session-secret
JWT_SECRET=dev-jwt-secret
# .env.production
RUSTELO_ENV=production
DATABASE_URL=postgresql://user:pass@host:5432/db
SESSION_SECRET=prod-session-secret
JWT_SECRET=prod-jwt-secret
# .env.staging
RUSTELO_ENV=staging
DATABASE_URL=postgresql://user:pass@staging-host:5432/db
SESSION_SECRET=staging-session-secret
JWT_SECRET=staging-jwt-secret
```
### Loading Environment Files
```bash
# Load development environment
source .env.development
# Load production environment
source .env.production
# Load with dotenv (if using dotenv tool)
dotenv -f .env.production -- ./rustelo-server
```
## Docker Configuration
### Docker Compose
```yaml
# docker-compose.yml
version: '3.8'
services:
app:
build: .
environment:
- RUSTELO_ENV=production
- DATABASE_URL=postgresql://rustelo:password@db:5432/rustelo
- SESSION_SECRET=your-session-secret
- JWT_SECRET=your-jwt-secret
- REDIS_URL=redis://redis:6379
env_file:
- .env.production
depends_on:
- db
- redis
db:
image: postgres:15
environment:
- POSTGRES_DB=rustelo
- POSTGRES_USER=rustelo
- POSTGRES_PASSWORD=password
redis:
image: redis:7-alpine
command: redis-server --requirepass your-redis-password
```
### Dockerfile
```dockerfile
FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release
FROM debian:bookworm-slim
# Install runtime dependencies
RUN apt-get update && apt-get install -y \
ca-certificates \
&& rm -rf /var/lib/apt/lists/*
COPY --from=builder /app/target/release/rustelo-server /usr/local/bin/
COPY --from=builder /app/config.prod.toml /etc/rustelo/config.toml
# Environment variables can be set here or passed at runtime
ENV RUSTELO_ENV=production
ENV RUSTELO_CONFIG_FILE=/etc/rustelo/config.toml
EXPOSE 3030
CMD ["rustelo-server"]
```
## Security Best Practices
### Secret Management
1. **Use Strong Secrets**
- Minimum 32 characters for session secrets
- Use cryptographically secure random generators
- Rotate secrets regularly
2. **Environment Separation**
- Never use production secrets in development
- Use different secrets for each environment
- Store secrets in secure vaults (HashiCorp Vault, AWS Secrets Manager)
3. **Access Control**
- Limit access to environment variables
- Use least privilege principle
- Audit secret access
### Example Secret Generation
```bash
# Generate secure session secret
openssl rand -base64 64
# Generate JWT secret
openssl rand -base64 64
# Generate encryption key
openssl rand -base64 32
# Generate CSRF secret
openssl rand -base64 32
```
## Validation and Testing
### Variable Validation
```bash
# Check required variables
./scripts/check-env.sh production
# Validate configuration
./config/scripts/build-config.sh prod --validate-only
```
### Testing Configuration
```bash
# Test with environment variables
RUSTELO_ENV=test DATABASE_URL=sqlite::memory: cargo test
# Test configuration loading
./rustelo-server --check-config
```
## Troubleshooting
### Common Issues
1. **Missing Environment Variables**
```bash
# Check if variables are set
env | grep RUSTELO
env | grep DATABASE_URL
```
2. **Invalid Variable Format**
```bash
# Validate database URL format
echo $DATABASE_URL | grep -E "^postgresql://"
```
3. **Permission Issues**
```bash
# Check file permissions for certificates
ls -la /etc/ssl/certs/yourapp.crt
```
### Debug Environment Loading
```bash
# Enable debug logging
RUST_LOG=rustelo=debug ./rustelo-server
# Show loaded configuration
./rustelo-server --show-config
```
## Migration Guide
When updating environment variables:
1. **Add new variables** to all environments
2. **Update documentation** with new requirements
3. **Provide default values** where possible
4. **Test thoroughly** in staging before production
5. **Update deployment scripts** and Docker configurations
For detailed migration instructions, see the [Environment Migration Guide](../reference/env-migration.md).

617
book/configuration/features.md
View File

@ -1,617 +0,0 @@
# Features Configuration
Rustelo's modular feature system allows you to enable, disable, and configure individual features based on your application's needs. This chapter covers how to configure features, understand their dependencies, and optimize your application by selecting the right combination of features.
## Overview
Features in Rustelo are:
- **Modular**: Each feature can be enabled/disabled independently
- **Configurable**: Features have their own configuration settings
- **Environment-Aware**: Different settings for development, staging, and production
- **Dependency-Aware**: Features can depend on other features
- **Performance-Optimized**: Unused features don't impact performance
## Feature System Architecture
```
features/
├── auth/ # Authentication & Authorization
│ ├── dev.toml # Development settings
│ ├── prod.toml # Production settings
│ └── example.toml # Example configuration
├── content/ # Content Management
├── email/ # Email System
├── metrics/ # Monitoring & Metrics
├── tls/ # SSL/TLS Security
├── rbac/ # Role-Based Access Control
└── cache/ # Caching System
```
## Core Features
### Authentication Feature
The authentication feature provides user authentication, session management, and security controls.
#### Configuration
```toml
[features]
auth = true
[auth.jwt]
secret = "${JWT_SECRET}"
expiration = 3600 # Token expiration in seconds
refresh_token_expiration = 604800 # Refresh token expiration (7 days)
algorithm = "HS256" # JWT algorithm
issuer = "rustelo-app" # JWT issuer
audience = "rustelo-users" # JWT audience
[auth.password]
min_length = 8 # Minimum password length
require_uppercase = true # Require uppercase letters
require_lowercase = true # Require lowercase letters
require_numbers = true # Require numbers
require_special_chars = true # Require special characters
max_age_days = 90 # Password expiration in days
history_count = 5 # Number of previous passwords to remember
[auth.security]
max_login_attempts = 5 # Maximum failed login attempts
lockout_duration = 900 # Account lockout duration in seconds
session_timeout = 1800 # Session timeout in seconds
require_email_verification = true # Require email verification
password_reset_timeout = 3600 # Password reset token timeout
[auth.two_factor]
enabled = true # Enable 2FA
backup_codes_count = 10 # Number of backup codes
totp_issuer = "Rustelo App" # TOTP issuer name
totp_digits = 6 # TOTP code length
totp_period = 30 # TOTP time period in seconds
[auth.sessions]
cleanup_interval = 3600 # Session cleanup interval in seconds
max_concurrent_sessions = 3 # Maximum concurrent sessions per user
remember_me_duration = 2592000 # Remember me duration (30 days)
```
#### Environment-Specific Settings
**Development:**
```toml
[auth.password]
min_length = 6
require_uppercase = false
require_special_chars = false
[auth.security]
max_login_attempts = 10
require_email_verification = false
```
**Production:**
```toml
[auth.password]
min_length = 12
require_uppercase = true
require_special_chars = true
[auth.security]
max_login_attempts = 3
require_email_verification = true
```
### Content Management Feature
The content feature provides content creation, editing, and management capabilities.
#### Configuration
```toml
[features]
content = true
[content]
enabled = true
content_dir = "content" # Content storage directory
cache_enabled = true # Enable content caching
cache_ttl = 3600 # Cache TTL in seconds
max_file_size = 10485760 # Maximum file size (10MB)
allowed_file_types = [ # Allowed file extensions
"md", "txt", "html", "css", "js", "json", "toml", "yaml"
]
[content.markdown]
enabled = true # Enable Markdown processing
syntax_highlighting = true # Enable code syntax highlighting
math_support = false # Enable LaTeX math rendering
table_of_contents = true # Generate table of contents
auto_links = true # Automatically link URLs
[content.media]
enabled = true # Enable media uploads
max_image_size = 5242880 # Maximum image size (5MB)
max_video_size = 52428800 # Maximum video size (50MB)
image_processing = true # Enable image processing
thumbnail_generation = true # Generate thumbnails
allowed_image_types = ["jpg", "jpeg", "png", "gif", "webp"]
allowed_video_types = ["mp4", "webm", "ogg"]
[content.versioning]
enabled = false # Enable content versioning
max_versions = 10 # Maximum versions to keep
auto_save_interval = 60 # Auto-save interval in seconds
[content.publishing]
draft_mode = true # Enable draft mode
scheduled_publishing = true # Enable scheduled publishing
approval_workflow = false # Require approval for publishing
```
### Email System Feature
The email feature provides email sending, templating, and queue management.
#### Configuration
```toml
[features]
email = true
[email]
enabled = true
provider = "smtp" # Email provider: smtp, sendgrid, console
from_email = "${FROM_EMAIL}" # Default sender email
from_name = "${FROM_NAME}" # Default sender name
reply_to = "" # Reply-to address
templates_dir = "templates/email" # Email templates directory
queue_enabled = true # Enable email queue
max_retries = 3 # Maximum retry attempts
retry_delay = 300 # Retry delay in seconds
[email.smtp]
host = "${SMTP_HOST}" # SMTP server host
port = 587 # SMTP server port
username = "${SMTP_USERNAME}" # SMTP username
password = "${SMTP_PASSWORD}" # SMTP password
use_tls = true # Use TLS encryption
use_starttls = true # Use STARTTLS
timeout = 30 # Connection timeout in seconds
[email.sendgrid]
api_key = "${SENDGRID_API_KEY}" # SendGrid API key
endpoint = "https://api.sendgrid.com/v3/mail/send" # SendGrid endpoint
[email.templates]
cache_enabled = true # Cache compiled templates
cache_ttl = 3600 # Template cache TTL
default_language = "en" # Default template language
```
### Metrics & Monitoring Feature
The metrics feature provides application monitoring, performance tracking, and observability.
#### Configuration
```toml
[features]
metrics = true
[metrics]
enabled = true
endpoint = "/metrics" # Metrics endpoint path
collect_interval = 15 # Collection interval in seconds
retention_days = 30 # Metrics retention period
[metrics.prometheus]
enabled = true # Enable Prometheus metrics
namespace = "rustelo" # Metrics namespace
subsystem = "app" # Metrics subsystem
labels = { version = "1.0.0", environment = "production" }
[metrics.system]
enabled = true # Collect system metrics
cpu_usage = true # Monitor CPU usage
memory_usage = true # Monitor memory usage
disk_usage = true # Monitor disk usage
network_usage = true # Monitor network usage
[metrics.application]
enabled = true # Collect application metrics
request_metrics = true # HTTP request metrics
database_metrics = true # Database query metrics
cache_metrics = true # Cache hit/miss metrics
error_metrics = true # Error rate metrics
[metrics.custom]
enabled = true # Enable custom metrics
business_metrics = true # Business-specific metrics
user_metrics = true # User activity metrics
```
### TLS/SSL Security Feature
The TLS feature provides SSL/TLS encryption, certificate management, and security headers.
#### Configuration
```toml
[features]
tls = true
[tls]
enabled = true
cert_file = "${TLS_CERT_FILE}" # Certificate file path
key_file = "${TLS_KEY_FILE}" # Private key file path
ca_file = "${TLS_CA_FILE}" # CA certificate file path
protocols = ["TLSv1.2", "TLSv1.3"] # Supported TLS protocols
ciphers = [ # Allowed cipher suites
"TLS_AES_256_GCM_SHA384",
"TLS_CHACHA20_POLY1305_SHA256",
"TLS_AES_128_GCM_SHA256"
]
[tls.security]
force_https = true # Force HTTPS redirects
hsts_enabled = true # Enable HSTS
hsts_max_age = 31536000 # HSTS max age (1 year)
hsts_include_subdomains = true # Include subdomains in HSTS
hsts_preload = true # Enable HSTS preload
[tls.certificates]
auto_renewal = true # Enable automatic certificate renewal
renewal_threshold = 2592000 # Renewal threshold (30 days)
acme_enabled = false # Enable ACME/Let's Encrypt
acme_directory = "https://acme-v02.api.letsencrypt.org/directory"
```
### Role-Based Access Control (RBAC)
The RBAC feature provides fine-grained access control, permissions, and role management.
#### Configuration
```toml
[features]
rbac = true
[rbac]
enabled = true
default_role = "user" # Default role for new users
admin_role = "admin" # Administrator role name
super_admin_role = "super_admin" # Super administrator role
[rbac.permissions]
hierarchical = true # Enable hierarchical permissions
inheritance = true # Enable permission inheritance
caching = true # Cache permission checks
cache_ttl = 300 # Permission cache TTL
[rbac.roles]
dynamic_roles = true # Enable dynamic role creation
role_templates = true # Enable role templates
role_expiration = false # Enable role expiration
[rbac.audit]
enabled = true # Enable audit logging
log_level = "info" # Audit log level
retention_days = 90 # Audit log retention period
```
### Caching System Feature
The caching feature provides multi-level caching for improved performance.
#### Configuration
```toml
[features]
cache = true
[cache]
enabled = true
default_ttl = 3600 # Default cache TTL in seconds
max_memory_size = 134217728 # Maximum memory cache size (128MB)
cleanup_interval = 300 # Cache cleanup interval in seconds
[cache.memory]
enabled = true # Enable in-memory caching
max_entries = 10000 # Maximum cache entries
eviction_policy = "lru" # Eviction policy: lru, lfu, random
[cache.redis]
enabled = false # Enable Redis caching
url = "${REDIS_URL}" # Redis connection URL
database = 0 # Redis database number
key_prefix = "rustelo:" # Cache key prefix
compression = true # Enable compression
[cache.file]
enabled = false # Enable file-based caching
cache_dir = "cache" # Cache directory
max_file_size = 1048576 # Maximum file size (1MB)
```
## Feature Dependencies
Some features depend on others. The system automatically handles these dependencies:
```toml
# Feature dependency matrix
[feature_dependencies]
rbac = ["auth"] # RBAC requires authentication
content = ["auth"] # Content management requires authentication
email = [] # Email has no dependencies
metrics = [] # Metrics has no dependencies
tls = [] # TLS has no dependencies
cache = [] # Cache has no dependencies
```
## Feature Flags
Feature flags allow runtime control of features:
```toml
[feature_flags]
auth_enabled = true
content_enabled = true
email_enabled = true
metrics_enabled = true
tls_enabled = true
rbac_enabled = false
cache_enabled = true
# Conditional features
[feature_flags.conditional]
oauth_enabled = false # Enable OAuth (requires auth)
two_factor_enabled = true # Enable 2FA (requires auth)
file_uploads_enabled = true # Enable file uploads (requires content)
```
## Environment-Specific Feature Configuration
### Development Environment
```toml
[features]
auth = true
content = true
email = true
metrics = true
tls = false
rbac = false
cache = true
[feature_flags]
debug_mode = true
mock_external_services = true
verbose_logging = true
```
### Production Environment
```toml
[features]
auth = true
content = true
email = true
metrics = true
tls = true
rbac = true
cache = true
[feature_flags]
debug_mode = false
mock_external_services = false
verbose_logging = false
performance_monitoring = true
```
## Performance Optimization
### Feature-Based Optimization
```toml
[optimization]
lazy_loading = true # Lazy load features
compile_time_optimization = true # Optimize at compile time
runtime_checks = false # Disable runtime feature checks in production
[optimization.features]
auth = { priority = "high", preload = true }
content = { priority = "medium", preload = false }
email = { priority = "low", preload = false }
metrics = { priority = "low", preload = false }
```
### Resource Management
```toml
[resource_limits]
max_memory_per_feature = 67108864 # 64MB per feature
max_cpu_per_feature = 10 # 10% CPU per feature
max_connections_per_feature = 100 # 100 connections per feature
```
## Feature Testing
### Test Configuration
```toml
[testing]
features_under_test = ["auth", "content"]
mock_dependencies = true
integration_tests = true
performance_tests = false
[testing.auth]
test_users = 1000
test_sessions = 100
test_roles = 10
[testing.content]
test_documents = 500
test_media_files = 100
test_versions = 5
```
## Creating Custom Features
### Feature Structure
```
features/my_feature/
├── dev.toml # Development configuration
├── prod.toml # Production configuration
├── example.toml # Example configuration
└── README.md # Feature documentation
```
### Example Custom Feature
```toml
# features/my_feature/dev.toml
[features]
my_feature = true
[my_feature]
enabled = true
debug_mode = true
api_endpoint = "http://localhost:8080"
timeout = 30
retry_count = 3
[my_feature.settings]
option1 = "value1"
option2 = 42
option3 = true
```
## Feature Management Commands
### Using Configuration Scripts
```bash
# List available features
./config/scripts/manage-config.sh list-features
# Enable a feature
./config/scripts/manage-config.sh enable-feature auth
# Disable a feature
./config/scripts/manage-config.sh disable-feature rbac
# Check feature dependencies
./config/scripts/manage-config.sh check-dependencies
# Validate feature configuration
./config/scripts/manage-config.sh validate-features
```
### Runtime Feature Management
```bash
# Check feature status
curl http://localhost:3030/admin/features
# Enable feature at runtime (if supported)
curl -X POST http://localhost:3030/admin/features/auth/enable
# Disable feature at runtime (if supported)
curl -X POST http://localhost:3030/admin/features/auth/disable
```
## Best Practices
### 1. Feature Selection
- **Start Small**: Begin with essential features only
- **Add Gradually**: Enable additional features as needed
- **Monitor Impact**: Watch performance metrics when adding features
- **Document Changes**: Keep track of feature changes and their impact
### 2. Configuration Management
- **Environment Consistency**: Use consistent feature sets across environments
- **Version Control**: Track feature configuration changes
- **Testing**: Test feature combinations thoroughly
- **Rollback Plan**: Have a plan for disabling problematic features
### 3. Performance Considerations
- **Resource Usage**: Monitor resource usage per feature
- **Startup Time**: Consider impact on application startup
- **Memory Usage**: Track memory consumption of enabled features
- **Database Impact**: Monitor database performance with features enabled
### 4. Security Considerations
- **Feature Isolation**: Ensure features don't interfere with each other
- **Access Control**: Implement proper access controls for feature management
- **Audit Logging**: Log feature changes and access
- **Security Testing**: Test security implications of feature combinations
## Troubleshooting
### Common Issues
1. **Feature Not Loading**
```bash
# Check feature configuration
./config/scripts/manage-config.sh validate-features
# Check feature dependencies
./config/scripts/manage-config.sh check-dependencies
```
2. **Performance Issues**
```bash
# Monitor feature resource usage
curl http://localhost:3030/metrics | grep feature_
# Check feature startup time
grep "feature.*initialized" logs/app.log
```
3. **Configuration Conflicts**
```bash
# Compare feature configurations
./config/scripts/manage-config.sh diff-features dev prod
```
### Debug Mode
Enable debug mode for detailed feature information:
```bash
RUSTELO_DEBUG=true FEATURE_DEBUG=true ./rustelo-server
```
## Migration Guide
When updating feature configurations:
1. **Backup Current Configuration**
```bash
./config/scripts/manage-config.sh backup-features
```
2. **Test New Configuration**
```bash
./config/scripts/manage-config.sh test-features
```
3. **Gradual Rollout**
- Update staging environment first
- Monitor for issues
- Update production environment
4. **Rollback if Needed**
```bash
./config/scripts/manage-config.sh restore-features backup-file
```
For detailed migration instructions, see the [Feature Migration Guide](../reference/feature-migration.md).

467
book/configuration/files.md
View File

@ -1,467 +0,0 @@
# Configuration Files
Rustelo uses a modular configuration system that separates concerns by features and environments. This system allows for flexible configuration management across different deployment scenarios while maintaining clear separation between base settings and feature-specific configurations.
## Overview
The configuration system consists of:
- **Base Configurations**: Core settings that apply to all features
- **Feature Configurations**: Settings specific to individual features
- **Environment-Specific Settings**: Optimized configurations for different environments
- **Configuration Management Scripts**: Tools for building, validating, and managing configurations
## Configuration Structure
```
config/
├── base/ # Base configurations
│ ├── dev.toml # Development base settings
│ ├── prod.toml # Production base settings
│ └── example.toml # Example/template base settings
├── features/ # Feature-specific configurations
│ ├── auth/ # Authentication feature
│ ├── email/ # Email feature
│ ├── tls/ # TLS/SSL feature
│ ├── content/ # Content management feature
│ └── metrics/ # Metrics and monitoring feature
├── scripts/ # Configuration management scripts
├── examples/ # Example configurations
└── README.md # Configuration documentation
```
## Base Configuration Files
Base configurations contain core settings that apply to all features:
### `base/dev.toml` - Development Environment
```toml
# Server Configuration
[server]
protocol = "http"
host = "127.0.0.1"
port = 3030
environment = "development"
log_level = "debug"
# Database Configuration
[database]
url = "sqlite//:dev_database.db"
max_connections = 5
enable_logging = true
# Session Management
[session]
secret = "dev-session-secret"
cookie_secure = false
max_age = 7200
# Security Settings (relaxed for development)
[security]
enable_csrf = false
rate_limit_requests = 1000
bcrypt_cost = 10
```
### `base/prod.toml` - Production Environment
```toml
# Server Configuration
[server]
protocol = "https"
host = "0.0.0.0"
port = 443
environment = "production"
log_level = "info"
# Database Configuration
[database]
url = "${DATABASE_URL}"
max_connections = 20
ssl_mode = "require"
# Session Management
[session]
secret = "${SESSION_SECRET}"
cookie_secure = true
max_age = 1800
# Security Settings (strict for production)
[security]
enable_csrf = true
rate_limit_requests = 100
bcrypt_cost = 12
```
## Feature Configuration Files
Feature configurations contain settings specific to individual features:
### Authentication Feature (`features/auth/`)
#### `features/auth/dev.toml`
```toml
[features]
auth = true
[auth.jwt]
secret = "dev-jwt-secret"
expiration = 86400
algorithm = "HS256"
[auth.password]
min_length = 6
require_uppercase = false
require_numbers = true
[auth.security]
max_login_attempts = 10
lockout_duration = 300
```
#### `features/auth/prod.toml`
```toml
[features]
auth = true
[auth.jwt]
secret = "${JWT_SECRET}"
expiration = 1800
algorithm = "HS256"
[auth.password]
min_length = 12
require_uppercase = true
require_numbers = true
require_special_chars = true
[auth.security]
max_login_attempts = 5
lockout_duration = 900
```
### Email Feature (`features/email/`)
#### `features/email/dev.toml`
```toml
[features]
email = true
[email]
provider = "console"
from_email = "dev@localhost"
templates_dir = "templates/email"
[email.smtp]
host = "localhost"
port = 1025
use_tls = false
```
#### `features/email/prod.toml`
```toml
[features]
email = true
[email]
provider = "smtp"
from_email = "${FROM_EMAIL}"
templates_dir = "templates/email"
[email.smtp]
host = "${SMTP_HOST}"
port = 587
username = "${SMTP_USERNAME}"
password = "${SMTP_PASSWORD}"
use_tls = true
```
## Environment Variables
Configuration files support environment variable substitution using `${VARIABLE_NAME}` syntax:
### Required Environment Variables
#### Development
- `DATABASE_URL` (optional, defaults to SQLite)
- `SESSION_SECRET` (optional, uses dev default)
#### Production
- `DATABASE_URL` (required)
- `SESSION_SECRET` (required)
- `JWT_SECRET` (required)
- `SMTP_HOST` (required if email enabled)
- `SMTP_USERNAME` (required if email enabled)
- `SMTP_PASSWORD` (required if email enabled)
- `FROM_EMAIL` (required if email enabled)
- `FRONTEND_URL` (required for CORS)
- `DOMAIN` (required for cookies)
### Environment Variable Examples
```bash
# Development
export DATABASE_URL="postgresql://user:password@localhost/rustelo_dev"
export SESSION_SECRET="your-session-secret-here"
# Production
export DATABASE_URL="postgresql://user:password@prod-db/rustelo"
export SESSION_SECRET="your-production-session-secret"
export JWT_SECRET="your-jwt-secret"
export SMTP_HOST="smtp.gmail.com"
export SMTP_USERNAME="your-app@gmail.com"
export SMTP_PASSWORD="your-app-password"
export FROM_EMAIL="noreply@yourapp.com"
export FRONTEND_URL="https://yourapp.com"
export DOMAIN="yourapp.com"
```
## Configuration Building
### Using Build Scripts
The configuration system includes scripts for building complete configuration files:
#### Shell Script
```bash
# Build development configuration
./config/scripts/build-config.sh dev
# Build production configuration
./config/scripts/build-config.sh prod config.prod.toml
# Build with validation only
CONFIG_VALIDATE_ONLY=1 ./config/scripts/build-config.sh dev
```
#### Python Script
```bash
# Build development configuration
./config/scripts/build-config.sh dev
# Build production configuration
./config/scripts/build-config.sh prod config.prod.toml
# Validate only
CONFIG_VALIDATE_ONLY=1 ./config/scripts/build-config.sh dev
```
### Management Script
The management script provides comprehensive configuration operations:
```bash
# Build configurations
./config/scripts/manage-config.sh build dev
./config/scripts/manage-config.sh build prod config.prod.toml
# Validate configurations
./config/scripts/manage-config.sh validate dev
# List features and environments
./config/scripts/manage-config.sh list-features
./config/scripts/manage-config.sh list-environments
# Compare configurations
./config/scripts/manage-config.sh diff dev prod
# Create backups
./config/scripts/manage-config.sh backup prod
```
## Configuration Validation
The system includes built-in validation for:
### Syntax Validation
- **TOML Syntax**: Ensures valid TOML structure
- **Type Checking**: Validates that values are of expected types
- **Required Fields**: Checks for presence of essential configuration sections
### Semantic Validation
- **Port Ranges**: Validates that ports are within valid ranges (1-65535)
- **Protocol Values**: Ensures protocols are valid (http, https)
- **Connection Limits**: Validates database connection pool settings
- **Feature Dependencies**: Checks that required features are enabled
### Security Validation
- **Secret Length**: Validates that secrets meet minimum length requirements
- **Password Policies**: Ensures password policies are configured securely
- **TLS Settings**: Validates SSL/TLS configuration for production
## Configuration Examples
### Complete Development Configuration
```toml
# Base settings
[server]
protocol = "http"
host = "127.0.0.1"
port = 3030
environment = "development"
[database]
url = "sqlite//:dev_database.db"
max_connections = 5
# Feature: Authentication
[features]
auth = true
[auth.jwt]
secret = "dev-jwt-secret"
expiration = 86400
# Feature: Email
[features]
email = true
[email]
provider = "console"
from_email = "dev@localhost"
# Build Information
[build_info]
environment = "dev"
build_time = "2024-01-01T12:00:00Z"
features = ["auth", "email"]
```
### Complete Production Configuration
```toml
# Base settings
[server]
protocol = "https"
host = "0.0.0.0"
port = 443
environment = "production"
[database]
url = "${DATABASE_URL}"
max_connections = 20
ssl_mode = "require"
# Feature: Authentication
[features]
auth = true
[auth.jwt]
secret = "${JWT_SECRET}"
expiration = 1800
[auth.password]
min_length = 12
require_uppercase = true
require_numbers = true
require_special_chars = true
# Feature: Email
[features]
email = true
[email]
provider = "smtp"
from_email = "${FROM_EMAIL}"
[email.smtp]
host = "${SMTP_HOST}"
port = 587
username = "${SMTP_USERNAME}"
password = "${SMTP_PASSWORD}"
use_tls = true
# Build Information
[build_info]
environment = "prod"
build_time = "2024-01-01T12:00:00Z"
features = ["auth", "email"]
```
## Best Practices
### 1. Environment-Specific Optimization
- **Development**: Prioritize developer experience and debugging
- **Production**: Prioritize security, performance, and reliability
- **Staging**: Mirror production settings with relaxed security for testing
### 2. Feature Independence
- Keep feature configurations independent of each other
- Use feature flags to enable/disable functionality
- Provide sensible defaults for all settings
### 3. Security
- Never commit sensitive values to version control
- Use environment variables for all secrets
- Implement proper validation for security-critical settings
- Use strong defaults for production environments
### 4. Documentation
- Document all configuration options in example files
- Provide clear descriptions for complex settings
- Include units and ranges for numeric values
- Maintain migration guides for configuration changes
## Troubleshooting
### Common Issues
1. **Invalid TOML Syntax**
```bash
# Validate syntax
./config/scripts/manage-config.sh validate dev
```
2. **Missing Environment Variables**
```bash
# Check required variables
env | grep -E "(DATABASE_URL|SESSION_SECRET|JWT_SECRET)"
```
3. **Feature Conflicts**
```bash
# Compare configurations
./config/scripts/manage-config.sh diff dev prod
```
### Debug Mode
Enable debug output for detailed information:
```bash
CONFIG_DEBUG=1 ./config/scripts/build-config.sh dev
```
### Validation Only
Validate configurations without building:
```bash
./config/scripts/manage-config.sh validate dev
CONFIG_VALIDATE_ONLY=1 ./config/scripts/build-config.sh prod
```
## Migration Guide
When upgrading configurations:
1. **Backup existing configurations**
2. **Update base configurations** for new settings
3. **Update feature configurations** as needed
4. **Test in development** before deploying to production
5. **Validate configurations** using the build scripts
6. **Update environment variables** if required
For detailed migration instructions, see the [Configuration Migration Guide](../reference/config-migration.md).

532
book/configuration/performance.md
View File

@ -1,532 +0,0 @@
# Performance Configuration
Rustelo provides extensive performance tuning options to optimize your application for different workloads and deployment scenarios. This chapter covers how to configure performance-related settings, optimize resource usage, and monitor application performance.
## Overview
Performance optimization in Rustelo covers:
- **Server Configuration**: Worker threads, connection limits, and request handling
- **Database Optimization**: Connection pooling, query optimization, and caching
- **Memory Management**: Heap size, garbage collection, and memory pools
- **Caching Systems**: Multi-level caching strategies and cache invalidation
- **Asset Optimization**: Static file serving, compression, and CDN integration
- **Monitoring & Profiling**: Performance metrics and bottleneck identification
## Server Performance Configuration
### Worker Thread Configuration
```toml
[server.performance]
workers = 8 # Number of worker threads (default: CPU cores)
worker_max_blocking_threads = 32 # Max blocking threads per worker
worker_thread_stack_size = 2097152 # Stack size per thread (2MB)
worker_thread_keep_alive = 60 # Keep-alive time for idle threads
max_connections = 10000 # Maximum concurrent connections
connection_timeout = 30 # Connection timeout in seconds
keep_alive_timeout = 65 # Keep-alive timeout
```
### Request Handling
```toml
[server.requests]
max_request_size = 52428800 # 50MB max request size
max_header_size = 32768 # 32KB max header size
max_uri_length = 8192 # 8KB max URI length
request_timeout = 30 # Request timeout in seconds
slow_request_threshold = 1000 # Log slow requests over 1 second
max_concurrent_requests = 1000 # Max concurrent requests
```
### Connection Management
```toml
[server.connections]
tcp_nodelay = true # Disable Nagle's algorithm
tcp_keepalive = true # Enable TCP keepalive
keepalive_time = 7200 # Keepalive time (2 hours)
keepalive_interval = 75 # Keepalive probe interval
keepalive_probes = 9 # Number of keepalive probes
reuse_port = true # Enable SO_REUSEPORT
backlog = 1024 # Listen backlog queue size
```
## Database Performance Configuration
### Connection Pool Optimization
```toml
[database.performance]
max_connections = 20 # Maximum pool size
min_connections = 5 # Minimum pool size
acquire_timeout = 30 # Connection acquire timeout
idle_timeout = 600 # Idle connection timeout
max_lifetime = 1800 # Maximum connection lifetime
test_before_acquire = false # Test connections before use
```
### Query Optimization
```toml
[database.queries]
statement_timeout = 30000 # Query timeout in milliseconds
slow_query_threshold = 1000 # Log slow queries over 1 second
enable_query_cache = true # Enable query result caching
query_cache_size = 134217728 # Query cache size (128MB)
query_cache_ttl = 300 # Query cache TTL in seconds
prepared_statement_cache_size = 256 # Prepared statement cache size
```
### Database-Specific Optimizations
#### PostgreSQL
```toml
[database.postgresql]
shared_buffers = "256MB" # Shared buffer size
effective_cache_size = "1GB" # Effective cache size
work_mem = "4MB" # Work memory per query
maintenance_work_mem = "64MB" # Maintenance work memory
checkpoint_completion_target = 0.7 # Checkpoint completion target
wal_buffers = "16MB" # WAL buffer size
default_statistics_target = 100 # Statistics target
random_page_cost = 1.1 # Random page cost
```
#### SQLite
```toml
[database.sqlite]
journal_mode = "WAL" # Write-Ahead Logging
synchronous = "NORMAL" # Synchronous mode
cache_size = 10000 # Page cache size
temp_store = "memory" # Temporary storage in memory
mmap_size = 268435456 # Memory-mapped I/O size (256MB)
page_size = 4096 # Page size in bytes
```
## Memory Management
### Heap Configuration
```toml
[memory]
initial_heap_size = 134217728 # Initial heap size (128MB)
max_heap_size = 2147483648 # Maximum heap size (2GB)
gc_threshold = 0.75 # GC threshold (75% of heap)
gc_trigger_interval = 60 # GC trigger interval in seconds
```
### Memory Pools
```toml
[memory.pools]
buffer_pool_size = 67108864 # Buffer pool size (64MB)
string_pool_size = 16777216 # String pool size (16MB)
object_pool_size = 33554432 # Object pool size (32MB)
connection_pool_memory = 8388608 # Connection pool memory (8MB)
```
### Memory Monitoring
```toml
[memory.monitoring]
track_allocations = true # Track memory allocations
memory_usage_threshold = 0.8 # Alert when memory usage > 80%
enable_memory_profiling = false # Enable memory profiling (dev only)
memory_leak_detection = true # Enable memory leak detection
```
## Caching Configuration
### Multi-Level Caching
```toml
[cache]
enabled = true
default_ttl = 3600 # Default cache TTL (1 hour)
max_memory_size = 268435456 # Max memory cache size (256MB)
cleanup_interval = 300 # Cache cleanup interval (5 minutes)
compression_enabled = true # Enable cache compression
compression_threshold = 1024 # Compress items larger than 1KB
```
### L1 Cache (In-Memory)
```toml
[cache.l1]
enabled = true
max_entries = 10000 # Maximum cache entries
eviction_policy = "lru" # Eviction policy: lru, lfu, fifo
segment_count = 16 # Number of cache segments
expire_after_write = 3600 # Expire after write (1 hour)
expire_after_access = 1800 # Expire after access (30 minutes)
```
### L2 Cache (Redis)
```toml
[cache.l2]
enabled = true
redis_url = "${REDIS_URL}"
database = 0 # Redis database number
key_prefix = "rustelo:" # Cache key prefix
connection_pool_size = 10 # Redis connection pool size
connection_timeout = 5 # Redis connection timeout
command_timeout = 5 # Redis command timeout
```
### Application-Level Caching
```toml
[cache.application]
page_cache_enabled = true # Enable page caching
page_cache_ttl = 1800 # Page cache TTL (30 minutes)
api_cache_enabled = true # Enable API response caching
api_cache_ttl = 300 # API cache TTL (5 minutes)
template_cache_enabled = true # Enable template caching
static_file_cache_enabled = true # Enable static file caching
```
## Asset Optimization
### Static File Serving
```toml
[assets]
serve_static_files = true # Serve static files
static_file_cache_control = "public, max-age=31536000" # 1 year cache
enable_etag = true # Enable ETag headers
enable_last_modified = true # Enable Last-Modified headers
enable_range_requests = true # Enable range requests
```
### Compression
```toml
[assets.compression]
enabled = true
algorithms = ["gzip", "deflate", "br"] # Compression algorithms
compression_level = 6 # Compression level (1-9)
min_file_size = 1024 # Minimum file size to compress
compress_types = [ # MIME types to compress
"text/html",
"text/css",
"text/javascript",
"application/javascript",
"application/json",
"text/xml",
"application/xml"
]
```
### CDN Integration
```toml
[assets.cdn]
enabled = false # Enable CDN
cdn_url = "https://cdn.example.com" # CDN base URL
cdn_paths = ["/static", "/assets"] # Paths to serve from CDN
cache_bust_enabled = true # Enable cache busting
cache_bust_strategy = "timestamp" # Strategy: timestamp, hash, version
```
## Performance Monitoring
### Metrics Collection
```toml
[performance.metrics]
enabled = true
collection_interval = 15 # Metrics collection interval (seconds)
retention_period = 2592000 # Metrics retention (30 days)
high_resolution_metrics = true # Enable high-resolution metrics
```
### Response Time Monitoring
```toml
[performance.response_times]
track_percentiles = true # Track response time percentiles
percentiles = [50, 75, 90, 95, 99, 99.9] # Percentiles to track
slow_request_threshold = 1000 # Slow request threshold (1 second)
very_slow_request_threshold = 5000 # Very slow request threshold (5 seconds)
```
### Resource Monitoring
```toml
[performance.resources]
monitor_cpu = true # Monitor CPU usage
monitor_memory = true # Monitor memory usage
monitor_disk = true # Monitor disk I/O
monitor_network = true # Monitor network I/O
monitor_connections = true # Monitor connection count
```
## Profiling Configuration
### CPU Profiling
```toml
[profiling.cpu]
enabled = false # Enable CPU profiling (dev/staging only)
sampling_interval = 10000 # Sampling interval in microseconds
profile_duration = 60 # Profile duration in seconds
output_format = "flamegraph" # Output format: flamegraph, callgrind
```
### Memory Profiling
```toml
[profiling.memory]
enabled = false # Enable memory profiling (dev/staging only)
track_allocations = true # Track individual allocations
heap_profiling = true # Enable heap profiling
leak_detection = true # Enable memory leak detection
```
### Database Profiling
```toml
[profiling.database]
enabled = false # Enable database profiling
log_all_queries = false # Log all database queries
log_slow_queries = true # Log slow queries only
explain_slow_queries = true # Add EXPLAIN to slow queries
query_plan_cache = true # Cache query execution plans
```
## Environment-Specific Performance
### Development Environment
```toml
[performance.development]
optimize_for_development = true # Enable development optimizations
hot_reload_enabled = true # Enable hot reloading
debug_mode = true # Enable debug mode
profiling_enabled = true # Enable profiling
reduced_caching = true # Reduce caching for development
```
### Production Environment
```toml
[performance.production]
optimize_for_production = true # Enable production optimizations
aggressive_caching = true # Enable aggressive caching
connection_pooling = true # Enable connection pooling
jit_compilation = true # Enable JIT compilation
gc_optimization = true # Enable garbage collection optimization
```
## Load Testing Configuration
### Test Parameters
```toml
[load_testing]
max_virtual_users = 1000 # Maximum virtual users
ramp_up_time = 60 # Ramp-up time in seconds
test_duration = 300 # Test duration in seconds
think_time = 1 # Think time between requests
```
### Performance Targets
```toml
[load_testing.targets]
response_time_p95 = 500 # 95th percentile response time (ms)
response_time_p99 = 1000 # 99th percentile response time (ms)
throughput_rps = 1000 # Requests per second
error_rate_threshold = 0.01 # Maximum error rate (1%)
cpu_usage_threshold = 0.8 # Maximum CPU usage (80%)
memory_usage_threshold = 0.8 # Maximum memory usage (80%)
```
## Performance Optimization Strategies
### Database Optimization
```toml
[optimization.database]
enable_query_optimization = true
index_optimization = true
query_caching = true
connection_pooling = true
read_replicas = false
database_sharding = false
```
### Application Optimization
```toml
[optimization.application]
lazy_loading = true # Enable lazy loading
async_processing = true # Enable async processing
batch_operations = true # Enable batch operations
response_streaming = true # Enable response streaming
request_coalescing = true # Enable request coalescing
```
### System Optimization
```toml
[optimization.system]
kernel_bypass = false # Enable kernel bypass (advanced)
numa_awareness = true # Enable NUMA awareness
cpu_affinity = false # Enable CPU affinity
disk_io_optimization = true # Enable disk I/O optimization
network_optimization = true # Enable network optimization
```
## Monitoring and Alerting
### Performance Alerts
```toml
[alerts.performance]
enabled = true
response_time_threshold = 2000 # Response time alert threshold (2 seconds)
throughput_threshold = 100 # Throughput alert threshold (100 RPS)
error_rate_threshold = 0.05 # Error rate alert threshold (5%)
memory_usage_threshold = 0.9 # Memory usage alert threshold (90%)
cpu_usage_threshold = 0.9 # CPU usage alert threshold (90%)
```
### Health Checks
```toml
[health_checks]
enabled = true
check_interval = 30 # Health check interval (seconds)
timeout = 5 # Health check timeout (seconds)
failure_threshold = 3 # Consecutive failures before alert
```
## Benchmarking Configuration
### Benchmark Settings
```toml
[benchmarking]
enabled = false # Enable benchmarking
benchmark_duration = 60 # Benchmark duration (seconds)
warmup_duration = 10 # Warmup duration (seconds)
concurrency_levels = [1, 10, 100, 1000] # Concurrency levels to test
```
### Performance Baselines
```toml
[benchmarking.baselines]
response_time_baseline = 100 # Response time baseline (ms)
throughput_baseline = 1000 # Throughput baseline (RPS)
memory_baseline = 134217728 # Memory baseline (128MB)
cpu_baseline = 0.5 # CPU baseline (50%)
```
## Troubleshooting Performance Issues
### Common Performance Problems
1. **High Response Times**
- Check database query performance
- Review caching configuration
- Monitor resource usage
- Analyze request patterns
2. **Memory Issues**
- Monitor memory usage patterns
- Check for memory leaks
- Review garbage collection settings
- Optimize memory allocation
3. **CPU Bottlenecks**
- Profile CPU usage
- Check for inefficient algorithms
- Review worker thread configuration
- Optimize hot code paths
4. **Database Performance**
- Analyze slow queries
- Check connection pool settings
- Review database configuration
- Optimize indexes
### Performance Debugging
```toml
[debugging.performance]
enable_detailed_logging = true # Enable detailed performance logging
request_tracing = true # Enable request tracing
sql_query_logging = true # Enable SQL query logging
memory_tracking = true # Enable memory tracking
cpu_profiling = true # Enable CPU profiling
```
## Best Practices
### Performance Optimization Guidelines
1. **Measure Before Optimizing**
- Establish performance baselines
- Use profiling tools
- Monitor key metrics
- Identify bottlenecks
2. **Optimize Incrementally**
- Make small, measurable changes
- Test each optimization
- Monitor impact
- Rollback if necessary
3. **Cache Strategically**
- Cache frequently accessed data
- Use appropriate cache levels
- Implement cache invalidation
- Monitor cache hit rates
4. **Database Optimization**
- Use appropriate indexes
- Optimize query structure
- Configure connection pooling
- Monitor slow queries
### Performance Testing
```toml
[testing.performance]
automated_testing = true # Enable automated performance testing
regression_testing = true # Enable performance regression testing
load_testing = true # Enable load testing
stress_testing = true # Enable stress testing
```
## Performance Checklist
### Pre-Production Performance Review
- [ ] Database queries optimized
- [ ] Appropriate indexes created
- [ ] Connection pooling configured
- [ ] Caching strategy implemented
- [ ] Static assets optimized
- [ ] Compression enabled
- [ ] Memory limits configured
- [ ] Worker threads optimized
- [ ] Performance monitoring enabled
- [ ] Load testing completed
- [ ] Performance baselines established
- [ ] Alerting configured
## Next Steps
- [Database Optimization](../performance/database.md)
- [Caching Strategies](../performance/caching.md)
- [Frontend Optimization](../performance/frontend.md)
- [Memory Management](../performance/memory.md)
- [Monitoring & Profiling](../performance/monitoring.md)

605
book/configuration/security.md
View File

@ -1,605 +0,0 @@
# Security Configuration
Rustelo provides comprehensive security features to protect your application and user data. This chapter covers how to configure authentication, authorization, encryption, and other security measures to ensure your application meets security best practices.
## Overview
Rustelo's security system includes:
- **Authentication**: User identity verification and session management
- **Authorization**: Role-based access control (RBAC) and permissions
- **Encryption**: Data protection at rest and in transit
- **Input Validation**: Protection against injection attacks
- **Security Headers**: HTTP security headers and CSP
- **Rate Limiting**: Protection against abuse and DoS attacks
- **Audit Logging**: Security event tracking and monitoring
## Authentication Configuration
### Basic Authentication Settings
```toml
[auth]
enabled = true
require_authentication = true
default_session_timeout = 1800 # 30 minutes
max_session_duration = 28800 # 8 hours
session_cleanup_interval = 300 # 5 minutes
[auth.password]
min_length = 12
max_length = 128
require_uppercase = true
require_lowercase = true
require_numbers = true
require_special_chars = true
forbidden_passwords = [
"password", "123456", "admin", "root"
]
password_history_count = 5
password_expiry_days = 90
```
### JWT Configuration
```toml
[auth.jwt]
secret = "${JWT_SECRET}"
algorithm = "HS256"
issuer = "rustelo-app"
audience = ["rustelo-users"]
access_token_expiry = 900 # 15 minutes
refresh_token_expiry = 86400 # 24 hours
require_exp = true
require_iat = true
require_nbf = true
clock_skew = 60 # Allow 60 seconds clock skew
```
### Session Management
```toml
[auth.sessions]
cookie_name = "rustelo_session"
cookie_secure = true # HTTPS only
cookie_http_only = true # No JavaScript access
cookie_same_site = "Strict"
cookie_path = "/"
cookie_domain = "" # Current domain only
session_regeneration = true # Regenerate session ID on login
concurrent_sessions = 3 # Max concurrent sessions per user
```
### Account Security
```toml
[auth.security]
max_login_attempts = 5
lockout_duration = 900 # 15 minutes
progressive_lockout = true # Increase lockout time on repeated failures
require_email_verification = true
email_verification_expiry = 86400 # 24 hours
password_reset_expiry = 3600 # 1 hour
```
## Two-Factor Authentication
### TOTP Configuration
```toml
[auth.two_factor]
enabled = true
required_for_admin = true
backup_codes_count = 10
backup_codes_length = 8
[auth.two_factor.totp]
issuer = "Rustelo App"
algorithm = "SHA1"
digits = 6
period = 30
window = 1 # Allow 1 step before/after current time
```
### SMS Configuration
```toml
[auth.two_factor.sms]
enabled = false
provider = "twilio" # twilio, aws_sns
verification_code_length = 6
verification_code_expiry = 300 # 5 minutes
rate_limit = 5 # Max 5 SMS per hour per user
[auth.two_factor.sms.twilio]
account_sid = "${TWILIO_ACCOUNT_SID}"
auth_token = "${TWILIO_AUTH_TOKEN}"
from_number = "${TWILIO_FROM_NUMBER}"
```
## Authorization & RBAC
### Role-Based Access Control
```toml
[rbac]
enabled = true
default_role = "user"
admin_role = "admin"
super_admin_role = "super_admin"
guest_role = "guest"
[rbac.permissions]
hierarchical = true # Roles inherit permissions from parent roles
cache_enabled = true
cache_ttl = 300 # 5 minutes
audit_enabled = true
[rbac.roles]
user = {
permissions = ["read_own_profile", "update_own_profile"],
inherits_from = ["guest"]
}
moderator = {
permissions = ["moderate_content", "view_reports"],
inherits_from = ["user"]
}
admin = {
permissions = ["manage_users", "manage_content", "view_logs"],
inherits_from = ["moderator"]
}
super_admin = {
permissions = ["*"],
inherits_from = []
}
```
### Resource-Based Permissions
```toml
[rbac.resources]
users = ["create", "read", "update", "delete"]
content = ["create", "read", "update", "delete", "publish"]
reports = ["create", "read", "update", "delete", "resolve"]
logs = ["read", "export"]
settings = ["read", "update"]
```
## Encryption Configuration
### Data Encryption
```toml
[encryption]
enabled = true
algorithm = "AES-256-GCM"
key_derivation = "PBKDF2"
key_derivation_iterations = 100000
salt_length = 32
[encryption.at_rest]
enabled = true
encrypt_sensitive_fields = true
sensitive_fields = [
"password", "email", "phone", "ssn", "credit_card"
]
[encryption.in_transit]
min_tls_version = "1.2"
cipher_suites = [
"TLS_AES_256_GCM_SHA384",
"TLS_CHACHA20_POLY1305_SHA256",
"TLS_AES_128_GCM_SHA256"
]
```
### Key Management
```toml
[encryption.keys]
rotation_enabled = true
rotation_interval = 2592000 # 30 days
key_backup_enabled = true
key_backup_location = "${KEY_BACKUP_PATH}"
master_key = "${MASTER_ENCRYPTION_KEY}"
```
## Input Validation & Sanitization
### General Validation
```toml
[security.validation]
enabled = true
strict_mode = true
max_request_size = 10485760 # 10MB
max_field_length = 1000
max_array_length = 100
max_nesting_depth = 10
[security.validation.email]
allow_plus_addressing = true
allow_internationalized = true
require_verification = true
blocked_domains = ["tempmail.com", "10minutemail.com"]
```
### SQL Injection Prevention
```toml
[security.sql_injection]
use_prepared_statements = true
validate_input_types = true
escape_special_characters = true
log_suspicious_queries = true
```
### XSS Prevention
```toml
[security.xss]
enabled = true
auto_escape_html = true
content_security_policy = true
sanitize_user_input = true
allowed_html_tags = ["b", "i", "u", "em", "strong", "a"]
allowed_attributes = ["href", "title", "alt"]
```
## Security Headers
### HTTP Security Headers
```toml
[security.headers]
enabled = true
[security.headers.hsts]
enabled = true
max_age = 31536000 # 1 year
include_subdomains = true
preload = true
[security.headers.csp]
enabled = true
default_src = ["'self'"]
script_src = ["'self'", "'unsafe-inline'"]
style_src = ["'self'", "'unsafe-inline'"]
img_src = ["'self'", "data:", "https:"]
connect_src = ["'self'"]
font_src = ["'self'"]
object_src = ["'none'"]
frame_ancestors = ["'none'"]
base_uri = ["'self'"]
form_action = ["'self'"]
[security.headers.other]
x_content_type_options = "nosniff"
x_frame_options = "DENY"
x_xss_protection = "1; mode=block"
referrer_policy = "strict-origin-when-cross-origin"
permissions_policy = "geolocation=(), microphone=(), camera=()"
```
## Rate Limiting
### API Rate Limiting
```toml
[security.rate_limiting]
enabled = true
storage = "memory" # memory, redis, database
cleanup_interval = 3600 # 1 hour
[security.rate_limiting.global]
requests_per_minute = 100
burst_limit = 10
[security.rate_limiting.per_user]
requests_per_minute = 60
burst_limit = 5
[security.rate_limiting.endpoints]
"/api/auth/login" = { requests_per_minute = 5, burst_limit = 2 }
"/api/auth/register" = { requests_per_minute = 3, burst_limit = 1 }
"/api/password/reset" = { requests_per_minute = 2, burst_limit = 1 }
"/api/upload" = { requests_per_minute = 10, burst_limit = 3 }
```
### DDoS Protection
```toml
[security.ddos]
enabled = true
max_connections_per_ip = 10
connection_timeout = 30
slow_loris_protection = true
```
## CSRF Protection
```toml
[security.csrf]
enabled = true
token_name = "csrf_token"
header_name = "X-CSRF-Token"
cookie_name = "csrf_cookie"
token_length = 32
double_submit_cookie = true
same_site_cookie = "Strict"
```
## File Upload Security
```toml
[security.uploads]
enabled = true
max_file_size = 10485760 # 10MB
max_files_per_request = 5
allowed_extensions = [
"jpg", "jpeg", "png", "gif", "webp",
"pdf", "doc", "docx", "txt", "csv"
]
scan_for_viruses = true
quarantine_suspicious_files = true
```
## Audit Logging
### Security Event Logging
```toml
[security.audit]
enabled = true
log_level = "info"
log_format = "json"
log_file = "/var/log/rustelo/security.log"
max_log_size = 104857600 # 100MB
max_log_files = 10
log_retention_days = 90
[security.audit.events]
login_success = true
login_failure = true
logout = true
password_change = true
password_reset = true
account_lockout = true
permission_denied = true
data_access = true
data_modification = true
admin_actions = true
```
### Compliance Logging
```toml
[security.compliance]
gdpr_logging = true
hipaa_logging = false
pci_logging = false
sox_logging = false
```
## Environment-Specific Security
### Development Environment
```toml
[security.development]
relaxed_cors = true
debug_headers = true
disable_https_redirect = true
allow_http_cookies = true
verbose_error_messages = true
```
### Production Environment
```toml
[security.production]
strict_mode = true
hide_server_info = true
disable_debug_endpoints = true
require_https = true
enable_monitoring = true
```
## SSL/TLS Configuration
### Certificate Management
```toml
[security.tls]
enabled = true
cert_file = "${TLS_CERT_FILE}"
key_file = "${TLS_KEY_FILE}"
ca_file = "${TLS_CA_FILE}"
protocols = ["TLSv1.2", "TLSv1.3"]
prefer_server_ciphers = true
[security.tls.auto_renewal]
enabled = true
provider = "lets_encrypt"
renewal_threshold = 2592000 # 30 days
notification_email = "${ADMIN_EMAIL}"
```
## Security Monitoring
### Intrusion Detection
```toml
[security.monitoring]
enabled = true
failed_login_threshold = 10
suspicious_activity_threshold = 5
alert_admin = true
auto_block_suspicious_ips = true
block_duration = 3600 # 1 hour
```
### Security Metrics
```toml
[security.metrics]
enabled = true
track_login_attempts = true
track_permission_denials = true
track_rate_limit_hits = true
track_security_violations = true
```
## Best Practices Configuration
### Password Security
```toml
[security.passwords]
use_bcrypt = true
bcrypt_cost = 12
require_password_confirmation = true
prevent_password_reuse = true
password_strength_meter = true
```
### API Security
```toml
[security.api]
require_authentication = true
require_https = true
validate_content_type = true
rate_limit_enabled = true
cors_enabled = true
cors_allow_credentials = false
```
## Security Testing
### Penetration Testing
```toml
[security.testing]
enable_security_tests = true
sql_injection_tests = true
xss_tests = true
csrf_tests = true
authentication_tests = true
authorization_tests = true
```
## Incident Response
### Security Incident Configuration
```toml
[security.incident_response]
enabled = true
auto_lockout_on_breach = true
notify_admin_on_incident = true
incident_log_file = "/var/log/rustelo/incidents.log"
emergency_contact = "${SECURITY_CONTACT}"
```
## Compliance Frameworks
### GDPR Compliance
```toml
[security.gdpr]
enabled = true
data_retention_days = 2555 # 7 years
anonymize_on_deletion = true
consent_tracking = true
data_export_enabled = true
```
### OWASP Configuration
```toml
[security.owasp]
top_10_protection = true
injection_prevention = true
broken_authentication_prevention = true
sensitive_data_exposure_prevention = true
xml_external_entities_prevention = true
broken_access_control_prevention = true
security_misconfiguration_prevention = true
cross_site_scripting_prevention = true
insecure_deserialization_prevention = true
known_vulnerabilities_prevention = true
insufficient_logging_prevention = true
```
## Security Checklist
### Pre-Deployment Security Checks
- [ ] Strong authentication configured
- [ ] HTTPS enabled and enforced
- [ ] Security headers implemented
- [ ] Input validation enabled
- [ ] Rate limiting configured
- [ ] Audit logging enabled
- [ ] File upload restrictions in place
- [ ] Database security configured
- [ ] Regular security updates scheduled
- [ ] Backup and recovery procedures tested
- [ ] Incident response plan documented
- [ ] Security monitoring enabled
- [ ] Penetration testing completed
- [ ] Compliance requirements met
## Troubleshooting
### Common Security Issues
1. **Authentication Failures**
- Check password policies
- Verify JWT configuration
- Review session settings
2. **Authorization Issues**
- Validate RBAC configuration
- Check permission inheritance
- Review role assignments
3. **SSL/TLS Problems**
- Verify certificate validity
- Check cipher suite compatibility
- Validate TLS version settings
4. **Rate Limiting Issues**
- Monitor rate limit logs
- Adjust limits based on usage
- Check for IP blocking
### Security Debugging
```bash
# Enable security debug logging
RUST_LOG=rustelo::security=debug ./rustelo-server
# Check security headers
curl -I https://yourapp.com
# Test authentication
curl -X POST https://yourapp.com/api/auth/login \
-H "Content-Type: application/json" \
-d '{"username":"test","password":"test"}'
```
## Security Resources
- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [NIST Cybersecurity Framework](https://www.nist.gov/cyberframework)
- [Mozilla Security Guidelines](https://infosec.mozilla.org/guidelines/)
- [Rust Security Guidelines](https://doc.rust-lang.org/nomicon/security.html)
## Next Steps
- [Authentication System](../developers/components/auth.md)
- [Performance Optimization](../performance/overview.md)
- [Monitoring & Logging](../deployment/monitoring.md)
- [Security Best Practices](../security/best-practices.md)

0
book/contributing/docs.md
View File

0
book/contributing/guide.md
View File

1
book/contributing/guidelines.md
View File

@ -1 +0,0 @@
# Contributing Guidelines

1
book/contributing/releases.md
View File

@ -1 +0,0 @@
# Release Process

0
book/contributing/setup.md
View File

0
book/contributing/standards.md
View File

0
book/contributing/testing.md
View File

0
book/database/abstraction.md
View File

0
book/database/migrations.md
View File

0
book/database/overview.md
View File

0
book/database/postgresql.md
View File

0
book/database/sqlite.md
View File

1
book/deployment/backup.md
View File

@ -1 +0,0 @@
# Backup & Recovery

1
book/deployment/cloud.md
View File

@ -1 +0,0 @@
# Cloud Platforms

0
book/deployment/docker.md
View File

0
book/deployment/environments.md
View File

0
book/deployment/monitoring.md
View File

0
book/deployment/overview.md
View File

0
book/deployment/production.md
View File

1
book/deployment/ssl.md
View File

@ -1 +0,0 @@
# SSL/TLS Configuration

1
book/developers/architecture/backend.md
View File

@ -1 +0,0 @@
# Backend Architecture

1
book/developers/architecture/database.md
View File

@ -1 +0,0 @@
# Database Design

1
book/developers/architecture/frontend.md
View File

@ -1 +0,0 @@
# Frontend Architecture

1
book/developers/architecture/overview.md
View File

@ -1 +0,0 @@
# System Overview

1
book/developers/architecture/security.md
View File

@ -1 +0,0 @@
# Security Model

329
book/developers/brand/logo-usage.md
View File

@ -1,329 +0,0 @@
# Logo Usage Guide
The Rustelo project includes a comprehensive logo system designed to work across different contexts and themes. This guide explains how to properly use the logos in your applications and documentation.
## Logo Assets
The logo system includes the following variants:
### Available Logo Files
| File | Usage | Context |
|------|-------|---------|
| `rustelo_dev-logo-h.svg` | Horizontal logo for normal/light themes | Primary horizontal logo |
| `rustelo_dev-logo-b-h.svg` | Horizontal logo for dark themes | Dark theme horizontal logo |
| `rustelo_dev-logo-v.svg` | Vertical logo for normal/light themes | Primary vertical logo |
| `rustelo_dev-logo-b-v.svg` | Vertical logo for dark themes | Dark theme vertical logo |
| `rustelo-imag.svg` | Logo image without text | Icon/favicon usage |
### Logo Locations
- **Source**: `logos/` directory (original assets)
- **Public**: `public/logos/` directory (web-accessible assets)
- **Documentation**: Referenced in mdBook via `../logos/` path
## Usage Guidelines
### 1. Web Application Usage
#### Navigation Logo
```rust
use crate::components::NavbarLogo;
// In your navigation component
view! {
<nav class="navigation">
<NavbarLogo size="small".to_string() />
// ... other nav items
</nav>
}
```
#### Brand Header
```rust
use crate::components::BrandHeader;
// For page headers
view! {
<BrandHeader
title="RUSTELO".to_string()
subtitle="Modular Rust Web Application Template".to_string()
logo_size="large".to_string()
class="justify-center".to_string()
/>
}
```
#### Standalone Logo
```rust
use crate::components::Logo;
// Basic logo usage
view! {
<Logo
orientation="horizontal".to_string()
size="medium".to_string()
show_text={true}
class="my-custom-class".to_string()
/>
}
```
### 2. Documentation Usage
#### Markdown Files
```markdown
<!-- In README.md or other markdown files -->
<div align="center">
<img src="logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
# Your Page Title
</div>
```
#### mdBook Pages
```markdown
<!-- In book pages -->
<div align="center">
<img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="400" />
</div>
# Welcome to Rustelo
```
### 3. Size Guidelines
#### Component Sizes
- **small**: 32px height (navbar usage)
- **medium**: 48px height (standard usage)
- **large**: 64px height (headers)
- **xlarge**: 80px height (hero sections)
#### Documentation Sizes
- **Small**: 150-200px width
- **Medium**: 250-300px width
- **Large**: 350-400px width
### 4. Responsive Usage
The logo components automatically adapt to different screen sizes:
```rust
// Mobile-responsive logo
view! {
<Logo
orientation="horizontal".to_string()
size="medium".to_string()
show_text={true}
class="w-full max-w-xs sm:max-w-sm md:max-w-md".to_string()
/>
}
```
## Theme Integration
### Automatic Theme Detection
The logo components automatically detect the current theme and switch between light and dark variants:
```rust
// This automatically uses the appropriate variant
view! {
<Logo
orientation="horizontal".to_string()
size="medium".to_string()
show_text={true}
/>
}
```
### Manual Theme Selection
For static contexts (like documentation), choose the appropriate variant:
- **Light backgrounds**: Use `rustelo_dev-logo-h.svg` or `rustelo_dev-logo-v.svg`
- **Dark backgrounds**: Use `rustelo_dev-logo-b-h.svg` or `rustelo_dev-logo-b-v.svg`
## Best Practices
### DO
✅ Use the horizontal logo for navigation bars and headers
✅ Use the vertical logo for sidebar or narrow layouts
✅ Use the image-only logo for favicons and small icons
✅ Maintain proper contrast with background colors
✅ Use consistent sizing within the same context
✅ Include proper alt text: "RUSTELO"
### DON'T
❌ Stretch or distort the logo proportions
❌ Use light logos on light backgrounds
❌ Use dark logos on dark backgrounds
❌ Make the logo too small to read (minimum 24px height)
❌ Use low-quality or pixelated versions
## Component API Reference
### Logo Component
```rust
#[component]
pub fn Logo(
#[prop(default = "horizontal".to_string())] orientation: String,
#[prop(default = "normal".to_string())] size: String,
#[prop(default = true)] show_text: bool,
#[prop(default = "".to_string())] class: String,
) -> impl IntoView
```
**Parameters:**
- `orientation`: "horizontal" | "vertical"
- `size`: "small" | "medium" | "large" | "xlarge"
- `show_text`: true (full logo) | false (image only)
- `class`: Additional CSS classes
### LogoLink Component
```rust
#[component]
pub fn LogoLink(
#[prop(default = "horizontal".to_string())] orientation: String,
#[prop(default = "normal".to_string())] size: String,
#[prop(default = true)] show_text: bool,
#[prop(default = "".to_string())] class: String,
#[prop(default = "/".to_string())] href: String,
) -> impl IntoView
```
**Additional Parameters:**
- `href`: Link destination (default: "/")
### BrandHeader Component
```rust
#[component]
pub fn BrandHeader(
#[prop(default = "RUSTELO".to_string())] title: String,
#[prop(default = "".to_string())] subtitle: String,
#[prop(default = "medium".to_string())] logo_size: String,
#[prop(default = "".to_string())] class: String,
) -> impl IntoView
```
**Parameters:**
- `title`: Main brand title
- `subtitle`: Optional subtitle text
- `logo_size`: Logo size variant
- `class`: Additional CSS classes
### NavbarLogo Component
```rust
#[component]
pub fn NavbarLogo(
#[prop(default = "small".to_string())] size: String,
#[prop(default = "".to_string())] class: String,
) -> impl IntoView
```
**Parameters:**
- `size`: Logo size (optimized for navbar)
- `class`: Additional CSS classes
## Usage Examples
### Hero Section
```rust
view! {
<section class="hero">
<BrandHeader
title="RUSTELO".to_string()
subtitle="Build fast, secure web applications with Rust".to_string()
logo_size="xlarge".to_string()
class="text-center".to_string()
/>
</section>
}
```
### Sidebar
```rust
view! {
<aside class="sidebar">
<Logo
orientation="vertical".to_string()
size="medium".to_string()
show_text={true}
class="mb-4".to_string()
/>
</aside>
}
```
### Footer
```rust
view! {
<footer class="footer">
<Logo
orientation="horizontal".to_string()
size="small".to_string()
show_text={false}
class="opacity-60".to_string()
/>
</footer>
}
```
## Troubleshooting
### Logo Not Displaying
1. **Check file paths**: Ensure logos are copied to `public/logos/`
2. **Verify imports**: Make sure components are properly imported
3. **Theme detection**: Confirm theme context is available
### Theme Switching Issues
1. **Theme provider**: Ensure `ThemeProvider` is properly configured
2. **CSS classes**: Check that theme-specific CSS is loaded
3. **JavaScript**: Verify theme switching JavaScript is working
### Performance Optimization
1. **SVG optimization**: Use optimized SVG files
2. **Lazy loading**: Add `loading="lazy"` for non-critical logos
3. **Caching**: Ensure proper cache headers for logo assets
## File Structure
```
template/
├── logos/ # Source logo files
│ ├── rustelo_dev-logo-h.svg
│ ├── rustelo_dev-logo-b-h.svg
│ ├── rustelo_dev-logo-v.svg
│ ├── rustelo_dev-logo-b-v.svg
│ └── rustelo-imag.svg
├── public/
│ └── logos/ # Web-accessible logo files
│ ├── rustelo_dev-logo-h.svg
│ ├── rustelo_dev-logo-b-h.svg
│ ├── rustelo_dev-logo-v.svg
│ ├── rustelo_dev-logo-b-v.svg
│ └── rustelo-imag.svg
└── client/src/components/
└── Logo.rs # Logo components
```
## Contributing
When adding new logo variants or updating existing ones:
1. Update both `logos/` and `public/logos/` directories
2. Test with both light and dark themes
3. Verify responsive behavior
4. Update this documentation
5. Test in all supported browsers
For questions or issues with logo usage, please refer to the [GitHub Issues](https://github.com/yourusername/rustelo/issues) page.

303
book/developers/components/README.md
View File

@ -1,303 +0,0 @@
# Rustelo Components
Welcome to the Rustelo Components documentation! This section covers all the built-in components and utilities available in the Rustelo framework.
## 📦 Available Components
### Authentication Components
- **[Authentication System](./auth.md)** - User authentication, JWT tokens, and session management
- Login/Register forms
- Password reset functionality
- User profile management
- Role-based access control
### Content Management
- **[Content System](./content.md)** - Content creation, editing, and management
- Markdown rendering
- File uploads and media management
- Content versioning
- Search functionality
### Email System
- **[Email Components](./email.md)** - Email sending and template management
- SMTP configuration
- Email templates
- Queue management
- Notification system
### Configuration
- **[Configuration System](./config.md)** - Application configuration management
- Environment-based configs
- Feature toggles
- Runtime configuration
- Validation and schema
### Templates & UI
- **[Template System](./templates.md)** - UI templates and components
- Responsive layouts
- Theme system
- Component library
- Style utilities
## 🎯 Component Architecture
Rustelo follows a modular component architecture where each component is:
- **Self-contained** - Each component manages its own state and dependencies
- **Configurable** - Components can be enabled/disabled via features
- **Extensible** - Easy to customize and extend for your needs
- **Well-documented** - Complete API documentation and examples
## 🚀 Getting Started
### Enable Components
Components are enabled through Cargo features:
```toml
[dependencies]
server = { path = "../server", features = ["auth", "content-db", "email"] }
```
### Basic Usage
```rust
use rustelo::components::{Auth, Content, Email};
// Initialize components
let auth = Auth::new(config.auth)?;
let content = Content::new(config.content)?;
let email = Email::new(config.email)?;
```
## 📋 Component Status
| Component | Status | Features | Documentation |
|-----------|--------|----------|---------------|
| Authentication | ✅ Complete | `auth` | [View](./auth.md) |
| Content Management | ✅ Complete | `content-db` | [View](./content.md) |
| Email System | ✅ Complete | `email` | [View](./email.md) |
| Configuration | ✅ Complete | Always enabled | [View](./config.md) |
| Templates | ✅ Complete | Always enabled | [View](./templates.md) |
## 🔧 Component Development
### Creating Custom Components
```rust
use rustelo::Component;
pub struct MyComponent {
config: MyConfig,
}
impl Component for MyComponent {
type Config = MyConfig;
fn new(config: Self::Config) -> Result<Self, Error> {
Ok(Self { config })
}
fn initialize(&mut self) -> Result<(), Error> {
// Initialize component
Ok(())
}
}
```
### Component Lifecycle
1. **Configuration** - Load component configuration
2. **Initialization** - Set up component state
3. **Registration** - Register routes and handlers
4. **Runtime** - Handle requests and events
5. **Cleanup** - Graceful shutdown
## 🎨 Frontend Components
### Leptos Components
```rust
use leptos::*;
use rustelo::components::*;
#[component]
pub fn App() -> impl IntoView {
view! {
<AuthProvider>
<ContentProvider>
<Router>
<Routes>
<Route path="/" view=HomePage/>
<Route path="/login" view=LoginPage/>
<Route path="/dashboard" view=DashboardPage/>
</Routes>
</Router>
</ContentProvider>
</AuthProvider>
}
}
```
### Styling Components
```rust
use rustelo::ui::*;
#[component]
pub fn MyPage() -> impl IntoView {
view! {
<Page title="My Page">
<Card>
<CardHeader>
<h2>"Welcome"</h2>
</CardHeader>
<CardBody>
<p>"Content goes here"</p>
</CardBody>
</Card>
</Page>
}
}
```
## 🔍 Component APIs
### Authentication API
```rust
// Check if user is authenticated
let is_authenticated = auth.is_authenticated(&request)?;
// Get current user
let user = auth.get_current_user(&request)?;
// Login user
let token = auth.login(&credentials)?;
```
### Content API
```rust
// Create content
let content = content_manager.create(CreateContentRequest {
title: "My Article".to_string(),
body: "Article content...".to_string(),
content_type: ContentType::Article,
})?;
// Get content
let content = content_manager.get_by_id(content_id)?;
```
### Email API
```rust
// Send email
email_service.send(SendEmailRequest {
to: "user@example.com".to_string(),
subject: "Welcome!".to_string(),
template: "welcome".to_string(),
data: serde_json::json!({
"name": "John Doe"
}),
})?;
```
## 📊 Performance Considerations
### Component Optimization
- **Lazy Loading** - Components are initialized only when needed
- **Caching** - Built-in caching for frequently accessed data
- **Connection Pooling** - Efficient database and external service connections
- **Async Operations** - Non-blocking I/O operations
### Resource Management
```rust
// Components automatically manage resources
impl Drop for MyComponent {
fn drop(&mut self) {
// Cleanup resources
self.cleanup();
}
}
```
## 🧪 Testing Components
### Unit Tests
```rust
#[cfg(test)]
mod tests {
use super::*;
use rustelo::testing::*;
#[tokio::test]
async fn test_auth_component() {
let config = test_config();
let auth = Auth::new(config.auth).unwrap();
// Test authentication
assert!(auth.is_authenticated(&test_request()).is_ok());
}
}
```
### Integration Tests
```rust
#[tokio::test]
async fn test_component_integration() {
let app = test_app().await;
// Test component interactions
let response = app.post("/api/auth/login")
.json(&login_request())
.send()
.await?;
assert_eq!(response.status(), 200);
}
```
## 🔐 Security
### Security Best Practices
- **Input Validation** - All inputs are validated and sanitized
- **Authentication** - Secure token-based authentication
- **Authorization** - Role-based access control
- **CSRF Protection** - Built-in CSRF token validation
- **Rate Limiting** - Configurable rate limiting
### Security Configuration
```toml
[security]
csrf_protection = true
rate_limiting = true
secure_cookies = true
https_only = true
```
## 📚 Next Steps
1. **[Authentication Guide](./auth.md)** - Set up user authentication
2. **[Content Management](./content.md)** - Manage application content
3. **[Email System](./email.md)** - Configure email functionality
4. **[Configuration](./config.md)** - Understand configuration options
5. **[Templates](./templates.md)** - Customize UI templates
## 🆘 Getting Help
- **[Common Issues](../../troubleshooting/common.md)** - Solutions to common problems
- **[API Reference](../../api/overview.md)** - Complete API documentation
- **[Examples](../../advanced/integrations.md)** - Real-world examples
- **Community Support** - Discord, GitHub Issues, Stack Overflow
---
**Happy building with Rustelo components!** 🦀✨

1
book/developers/components/auth.md
View File

@ -1 +0,0 @@
# Authentication System

1
book/developers/components/config.md
View File

@ -1 +0,0 @@
# Configuration System

1
book/developers/components/content.md
View File

@ -1 +0,0 @@
# Content Management

766
book/developers/components/email.md
View File

@ -1,766 +0,0 @@
# Email System
<div align="center">
<img src="../../../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
</div>
This guide covers RUSTELO's comprehensive email system, including setup, configuration, usage, and best practices for integrating email functionality into your application.
## Overview
The RUSTELO email system provides a complete solution for sending emails from your web application with support for multiple providers, template-based emails, form submissions, and both server-side and client-side integration.
### Architecture
- **Email Service**: Core service that handles email sending
- **Providers**: Pluggable email providers (SMTP, SendGrid, Console)
- **Templates**: Handlebars-based email templates
- **Forms**: Ready-to-use contact and support form components
- **API**: REST endpoints for email operations
## Features
✨ **Multiple Providers**
- SMTP (Gmail, Outlook, custom servers)
- SendGrid API
- Console output (development)
📧 **Template System**
- Handlebars templates
- HTML and text versions
- Custom helpers
- Variable substitution
🔧 **Form Integration**
- Contact forms
- Support forms with priorities
- Custom form handling
🛡️ **Security**
- Input validation
- Rate limiting
- CSRF protection
- Secure configuration
🎨 **Rich Components**
- React/Leptos form components
- Real-time validation
- Error handling
- Success feedback
## Quick Start
### 1. Enable Email Feature
Make sure the email feature is enabled in your `Cargo.toml`:
```toml
[features]
default = ["email"]
email = ["lettre", "handlebars", "urlencoding"]
```
### 2. Basic Configuration
Add email configuration to your `config.toml`:
```toml
[email]
enabled = true
provider = "console" # Start with console for development
from_email = "noreply@yourapp.com"
from_name = "Your App"
template_dir = "templates/email"
```
### 3. Create Template Directory
```bash
mkdir -p templates/email/html
mkdir -p templates/email/text
```
### 4. Start Using
```rust
// Send a simple email
let result = email_service.send_simple_email(
"user@example.com",
"Welcome!",
"Thank you for signing up!"
).await?;
// Send a contact form
let result = email_service.send_contact_form(
"John Doe",
"john@example.com",
"Question about pricing",
"I'd like to know more about your pricing plans.",
"admin@yourapp.com"
).await?;
```
## Configuration
### Email Configuration Options
```toml
[email]
# Basic settings
enabled = true
provider = "smtp" # "smtp", "sendgrid", "console"
from_email = "noreply@yourapp.com"
from_name = "Your App Name"
template_dir = "templates/email"
# SMTP settings (when provider = "smtp")
smtp_host = "smtp.gmail.com"
smtp_port = 587
smtp_username = "your-email@gmail.com"
smtp_password = "@encrypted_smtp_password"
smtp_use_tls = false
smtp_use_starttls = true
# SendGrid settings (when provider = "sendgrid")
sendgrid_api_key = "@encrypted_sendgrid_api_key"
sendgrid_endpoint = "https://api.sendgrid.com/v3/mail/send"
```
### Environment-Specific Configuration
```toml
# Development
[environments.development]
email.provider = "console"
email.enabled = true
# Production
[environments.production]
email.provider = "sendgrid"
email.sendgrid_api_key = "@encrypted_sendgrid_api_key"
email.enabled = true
```
## Email Providers
### Console Provider
Perfect for development and testing. Prints emails to the console.
```toml
[email]
provider = "console"
```
**Features:**
- No external dependencies
- Immediate feedback
- Safe for development
### SMTP Provider
Use any SMTP server including Gmail, Outlook, or custom servers.
```toml
[email]
provider = "smtp"
smtp_host = "smtp.gmail.com"
smtp_port = 587
smtp_username = "your-email@gmail.com"
smtp_password = "@encrypted_smtp_password"
smtp_use_starttls = true
```
**Common SMTP Configurations:**
**Gmail:**
```toml
smtp_host = "smtp.gmail.com"
smtp_port = 587
smtp_use_starttls = true
# Requires App Password (not regular password)
```
**Outlook:**
```toml
smtp_host = "smtp-mail.outlook.com"
smtp_port = 587
smtp_use_starttls = true
```
**Custom SMTP:**
```toml
smtp_host = "mail.yourserver.com"
smtp_port = 587
smtp_use_starttls = true
```
### SendGrid Provider
Use SendGrid's API for reliable email delivery.
```toml
[email]
provider = "sendgrid"
sendgrid_api_key = "@encrypted_sendgrid_api_key"
```
**Features:**
- High deliverability
- Built-in analytics
- Bounce handling
- Reliable service
## Templates
### Template Structure
```
templates/email/
├── html/
│ ├── contact.hbs
│ ├── support.hbs
│ ├── welcome.hbs
│ └── notification.hbs
└── text/
├── contact.hbs
├── support.hbs
├── welcome.hbs
└── notification.hbs
```
### Template Naming
- `contact.hbs` - Contact form emails
- `support.hbs` - Support form emails
- `welcome.hbs` - Welcome/registration emails
- `notification.hbs` - General notifications
### Handlebars Helpers
Built-in helpers for common email tasks:
- `{{format_date}}` - Format dates
- `{{format_currency}}` - Format money
- `{{upper}}` - Uppercase text
- `{{lower}}` - Lowercase text
- `{{capitalize}}` - Capitalize words
### Example Template
**templates/email/html/contact.hbs:**
```html
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Contact Form Submission</title>
<style>
body { font-family: Arial, sans-serif; margin: 20px; }
.header { background-color: #f8f9fa; padding: 20px; border-radius: 8px; }
.content { margin: 20px 0; }
.footer { color: #666; font-size: 12px; }
</style>
</head>
<body>
<div class="header">
<h1>New Contact Form Submission</h1>
</div>
<div class="content">
<p><strong>Name:</strong> {{name}}</p>
<p><strong>Email:</strong> {{email}}</p>
<p><strong>Subject:</strong> {{subject}}</p>
<p><strong>Message:</strong></p>
<p>{{message}}</p>
</div>
<div class="footer">
<p>Sent at {{format_date timestamp}}</p>
</div>
</body>
</html>
```
**templates/email/text/contact.hbs:**
```text
New Contact Form Submission
Name: {{name}}
Email: {{email}}
Subject: {{subject}}
Message:
{{message}}
Sent at {{format_date timestamp}}
```
## API Endpoints
### GET /api/email/status
Check email system status.
**Response:**
```json
{
"enabled": true,
"provider": "smtp",
"configured": true,
"templates": ["contact", "support", "welcome", "notification"]
}
```
### POST /api/email/contact
Send a contact form email.
**Request:**
```json
{
"name": "John Doe",
"email": "john@example.com",
"subject": "Question about pricing",
"message": "I'd like to know more about your pricing plans.",
"recipient": "admin@yourapp.com"
}
```
**Response:**
```json
{
"message": "Email sent successfully",
"message_id": "abc123def456",
"status": "sent"
}
```
### POST /api/email/support
Send a support form email with priority.
**Request:**
```json
{
"name": "Jane Smith",
"email": "jane@example.com",
"subject": "Technical Issue",
"message": "Having trouble with login functionality.",
"priority": "high",
"category": "technical",
"recipient": "support@yourapp.com"
}
```
### POST /api/email/send
Send a template-based email.
**Request:**
```json
{
"to": "user@example.com",
"subject": "Welcome to Our Platform",
"template": "welcome",
"template_data": {
"user_name": "John Doe",
"activation_link": "https://yourapp.com/activate/token123"
}
}
```
### POST /api/email/notification
Send a notification email.
**Request:**
```json
{
"to": "user@example.com",
"title": "Important Update",
"message": "Your account has been updated successfully.",
"content": "Additional details about the update..."
}
```
## Client Components
### ContactForm Component
```rust
#[component]
pub fn ContactForm() -> impl IntoView {
let (form_data, set_form_data) = create_signal(ContactFormData::default());
let (is_submitting, set_is_submitting) = create_signal(false);
let (message, set_message) = create_signal(String::new());
let submit_form = create_action(move |data: &ContactFormData| {
let data = data.clone();
async move {
set_is_submitting(true);
let result = send_contact_form(data).await;
set_is_submitting(false);
match result {
Ok(_) => set_message("Thank you for your message! We'll get back to you soon.".to_string()),
Err(e) => set_message(format!("Error sending message: {}", e)),
}
}
});
view! {
<div class="contact-form">
<h2>"Contact Us"</h2>
<form on:submit=move |ev| {
ev.prevent_default();
submit_form.dispatch(form_data.get());
}>
<div class="form-group">
<label for="name">"Name"</label>
<input
type="text"
id="name"
required
on:input=move |ev| {
set_form_data.update(|data| data.name = event_target_value(&ev));
}
/>
</div>
<div class="form-group">
<label for="email">"Email"</label>
<input
type="email"
id="email"
required
on:input=move |ev| {
set_form_data.update(|data| data.email = event_target_value(&ev));
}
/>
</div>
<div class="form-group">
<label for="subject">"Subject"</label>
<input
type="text"
id="subject"
required
on:input=move |ev| {
set_form_data.update(|data| data.subject = event_target_value(&ev));
}
/>
</div>
<div class="form-group">
<label for="message">"Message"</label>
<textarea
id="message"
required
on:input=move |ev| {
set_form_data.update(|data| data.message = event_target_value(&ev));
}
></textarea>
</div>
<button type="submit" disabled=move || is_submitting.get()>
{move || if is_submitting.get() { "Sending..." } else { "Send Message" }}
</button>
</form>
<Show when=move || !message.get().is_empty()>
<div class="message">{move || message.get()}</div>
</Show>
</div>
}
}
```
### SupportForm Component
```rust
#[component]
pub fn SupportForm() -> impl IntoView {
let (form_data, set_form_data) = create_signal(SupportFormData::default());
let (is_submitting, set_is_submitting) = create_signal(false);
let (message, set_message) = create_signal(String::new());
let submit_form = create_action(move |data: &SupportFormData| {
let data = data.clone();
async move {
set_is_submitting(true);
let result = send_support_form(data).await;
set_is_submitting(false);
match result {
Ok(_) => set_message("Support ticket submitted successfully!".to_string()),
Err(e) => set_message(format!("Error submitting ticket: {}", e)),
}
}
});
view! {
<div class="support-form">
<h2>"Support Request"</h2>
<form on:submit=move |ev| {
ev.prevent_default();
submit_form.dispatch(form_data.get());
}>
// Similar form fields with priority selector
<div class="form-group">
<label for="priority">"Priority"</label>
<select
id="priority"
on:change=move |ev| {
set_form_data.update(|data| data.priority = event_target_value(&ev));
}
>
<option value="low">"Low"</option>
<option value="medium">"Medium"</option>
<option value="high">"High"</option>
<option value="urgent">"Urgent"</option>
</select>
</div>
<button type="submit" disabled=move || is_submitting.get()>
{move || if is_submitting.get() { "Submitting..." } else { "Submit Ticket" }}
</button>
</form>
</div>
}
}
```
## Server Usage
### Basic Email Sending
```rust
use server::email::{EmailService, EmailConfig};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let config = EmailConfig::from_file("config.toml")?;
let email_service = EmailService::new(config).await?;
// Send simple email
email_service.send_simple_email(
"user@example.com",
"Welcome!",
"Thank you for signing up!"
).await?;
Ok(())
}
```
### Template-Based Emails
```rust
use std::collections::HashMap;
#[server(SendWelcomeEmail, "/api/email/welcome")]
pub async fn send_welcome_email(
email: String,
name: String,
activation_token: String,
) -> Result<String, ServerFnError> {
let email_service = get_email_service().await?;
let mut template_data = HashMap::new();
template_data.insert("user_name".to_string(), name);
template_data.insert("activation_link".to_string(),
format!("https://yourapp.com/activate/{}", activation_token));
email_service.send_template_email(
&email,
"Welcome to Our Platform",
"welcome",
template_data
).await?;
Ok("Welcome email sent successfully".to_string())
}
```
### Form Handling
```rust
#[server(HandleContactForm, "/api/email/contact")]
pub async fn handle_contact_form(
name: String,
email: String,
subject: String,
message: String,
) -> Result<String, ServerFnError> {
let email_service = get_email_service().await?;
// Validate input
if name.is_empty() || email.is_empty() || message.is_empty() {
return Err(ServerFnError::ServerError("All fields are required".to_string()));
}
// Send email
email_service.send_contact_form(
&name,
&email,
&subject,
&message,
"admin@yourapp.com"
).await?;
Ok("Contact form submitted successfully".to_string())
}
```
## Environment Variables
### Common Variables
```bash
# SMTP Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_USE_STARTTLS=true
# SendGrid Configuration
SENDGRID_API_KEY=your-sendgrid-api-key
# Email Settings
EMAIL_FROM=noreply@yourapp.com
EMAIL_FROM_NAME="Your App"
```
### Using in Configuration
```toml
[email]
smtp_username = "${SMTP_USERNAME}"
smtp_password = "@encrypted_smtp_password"
sendgrid_api_key = "@encrypted_sendgrid_api_key"
from_email = "${EMAIL_FROM}"
```
## Security Considerations
### 1. Credential Management
Always encrypt sensitive credentials:
```bash
# Encrypt SMTP password
cargo run --bin config_crypto_tool encrypt "your-smtp-password"
# Encrypt SendGrid API key
cargo run --bin config_crypto_tool encrypt "your-sendgrid-api-key"
```
### 2. Input Validation
Always validate email inputs:
```rust
use validator::{Validate, ValidationError};
#[derive(Validate)]
struct ContactFormData {
#[validate(length(min = 1, message = "Name is required"))]
name: String,
#[validate(email(message = "Invalid email address"))]
email: String,
#[validate(length(min = 1, max = 1000, message = "Message must be between 1 and 1000 characters"))]
message: String,
}
```
### 3. Rate Limiting
Implement rate limiting for email endpoints:
```rust
use tower_governor::{governor::GovernorLayer, GovernorConfigBuilder};
// Limit to 5 emails per minute per IP
let governor_config = GovernorConfigBuilder::default()
.per_minute(5)
.burst_size(2)
.finish()
.unwrap();
let governor_layer = GovernorLayer {
config: Arc::new(governor_config),
};
```
### 4. CSRF Protection
Enable CSRF protection for email forms:
```rust
use axum_csrf::{CsrfConfig, CsrfLayer};
let csrf_config = CsrfConfig::default();
let csrf_layer = CsrfLayer::new(csrf_config);
```
## Troubleshooting
### Common Issues
**Email not sending:**
- Check provider configuration
- Verify credentials
- Check network connectivity
- Review email service logs
**Template not found:**
- Verify template directory path
- Check template file naming
- Ensure HTML and text versions exist
**Authentication failed:**
- For Gmail: Use App Password, not regular password
- For other providers: Check username/password
- Verify server and port settings
**Rate limiting:**
- Check provider limits
- Implement proper rate limiting
- Consider using queues for bulk emails
### Debug Mode
Enable debug logging to troubleshoot issues:
```toml
[logging]
level = "debug"
[email]
enabled = true
debug = true
```
## Best Practices
1. **Use encrypted configuration** for sensitive credentials
2. **Implement proper validation** for all email inputs
3. **Use rate limiting** to prevent abuse
4. **Provide both HTML and text** versions of templates
5. **Test with console provider** during development
6. **Monitor email delivery** in production
7. **Handle errors gracefully** with user-friendly messages
8. **Use meaningful subject lines** and sender names
## Next Steps
- [API Reference](../../api/email.md)
- [Security Best Practices](../../security/best-practices.md)
- [Configuration Guide](../../configuration/files.md)
- [Deployment Guide](../../deployment/production.md)
The email system provides a robust foundation for all your application's communication needs while maintaining security and reliability.

1
book/developers/components/templates.md
View File

@ -1 +0,0 @@
# Template Engine

1
book/developers/features/adding-features.md
View File

@ -1 +0,0 @@
# Adding New Features

1
book/developers/features/api-endpoints.md
View File

@ -1 +0,0 @@
# API Endpoints

1
book/developers/features/feature-flags.md
View File

@ -1 +0,0 @@
# Feature Flags & Modules

1
book/developers/features/frontend-components.md
View File

@ -1 +0,0 @@
# Frontend Components

1
book/developers/setup/build.md
View File

@ -1 +0,0 @@
# Build System & Tools

1
book/developers/setup/environment.md
View File

@ -1 +0,0 @@
# Development Environment

1
book/developers/setup/structure.md
View File

@ -1 +0,0 @@
# Project Structure

1
book/developers/setup/workflow.md
View File

@ -1 +0,0 @@
# Development Workflow

1
book/developers/testing/e2e.md
View File

@ -1 +0,0 @@
# End-to-End Testing

1
book/developers/testing/integration.md
View File

@ -1 +0,0 @@
# Integration Testing

1
book/developers/testing/performance.md
View File

@ -1 +0,0 @@
# Performance Testing

1
book/developers/testing/strategy.md
View File

@ -1 +0,0 @@
# Testing Strategy

1
book/developers/testing/unit.md
View File

@ -1 +0,0 @@
# Unit Testing

0
book/development/debugging.md
View File

0
book/development/hot-reloading.md
View File

0
book/development/setup.md
View File

0
book/development/structure.md
View File

0
book/development/testing.md
View File

0
book/development/workflow.md
View File

0
book/features/auth/jwt.md
View File

0
book/features/auth/oauth2.md
View File

0
book/features/auth/sessions.md
View File

0
book/features/authentication.md
View File

0
book/features/combinations.md
View File

0
book/features/content-management.md
View File

0
book/features/content/database.md
View File

0
book/features/content/markdown.md
View File

0
book/features/content/static.md
View File

315
book/features/detailed.md
View File

@ -1,315 +0,0 @@
# Rustelo Features Configuration
<div align="center">
<img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
</div>
This document describes the optional features available in the Rustelo template and how to configure them.
## Available Features
### Default Features
By default, the following features are enabled:
- `auth` - Authentication and authorization system
- `content-db` - Database-driven content management
### Optional Features
#### 1. TLS (`tls`)
Enables HTTPS/TLS support for secure connections.
**Dependencies:**
- `axum-server` with TLS support
- `rustls` for TLS implementation
- `rustls-pemfile` for PEM file handling
**Configuration:**
```bash
# Environment variables
SERVER_PROTOCOL=https
TLS_CERT_PATH=/path/to/certificate.pem
TLS_KEY_PATH=/path/to/private_key.pem
```
**Usage:**
```bash
# Enable TLS feature
cargo build --features tls
# Run with TLS
SERVER_PROTOCOL=https TLS_CERT_PATH=./certs/cert.pem TLS_KEY_PATH=./certs/key.pem cargo run
```
#### 2. Authentication (`auth`)
Comprehensive authentication and authorization system including:
- JWT token-based authentication
- OAuth2 providers (Google, GitHub, etc.)
- Two-factor authentication (2FA/TOTP)
- Password hashing with Argon2
- Session management
**Dependencies:**
- `jsonwebtoken` - JWT handling
- `argon2` - Password hashing
- `oauth2` - OAuth2 client
- `totp-rs` - Two-factor authentication
- `qrcode` - QR code generation for 2FA setup
- `tower-sessions` - Session management
- `sqlx` - Database access
**API Endpoints:**
- `/api/auth/login` - User login
- `/api/auth/logout` - User logout
- `/api/auth/register` - User registration
- `/api/auth/refresh` - Token refresh
- `/api/auth/oauth/google` - Google OAuth
- `/api/auth/oauth/github` - GitHub OAuth
- `/api/auth/2fa/setup` - 2FA setup
- `/api/auth/2fa/verify` - 2FA verification
**Configuration:**
```bash
# Database connection
DATABASE_URL=postgres://username:password@localhost:5432/database_name
# JWT configuration
JWT_SECRET=your-jwt-secret-key
JWT_EXPIRATION_HOURS=24
# OAuth providers
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
```
#### 3. Database Content (`content-db`)
Database-driven content management system with:
- Markdown content rendering
- Syntax highlighting
- YAML frontmatter support
- Content caching
- Dynamic content loading
**Dependencies:**
- `pulldown-cmark` - Markdown parsing
- `syntect` - Syntax highlighting
- `serde_yaml` - YAML frontmatter
- `sqlx` - Database access
**API Endpoints:**
- `/api/content/pages` - List pages
- `/api/content/page/{slug}` - Get page by slug
- `/api/content/posts` - List blog posts
- `/api/content/post/{slug}` - Get post by slug
**Configuration:**
```bash
# Database connection
DATABASE_URL=postgres://username:password@localhost:5432/database_name
# Content configuration
CONTENT_CACHE_ENABLED=true
CONTENT_CACHE_TTL=3600
```
## Feature Combinations
### Minimal Setup (No optional features)
```bash
cargo build --no-default-features
```
This provides a basic Leptos application with static content only.
### Basic Setup (No database)
```bash
cargo build --no-default-features --features tls
```
Basic application with TLS support but no database features.
### Authentication Only
```bash
cargo build --no-default-features --features auth
```
Includes authentication system but no database content management.
### Content Management Only
```bash
cargo build --no-default-features --features content-db
```
Includes database-driven content but no authentication.
### Full Featured (Default)
```bash
cargo build --features "auth,content-db"
# or simply
cargo build
```
All features enabled for a complete application.
### Production Setup
```bash
cargo build --release --features "tls,auth,content-db"
```
Full featured application with TLS for production deployment.
## Environment Configuration
Create a `.env` file in your project root:
```env
# Server configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=3030
SERVER_PROTOCOL=http
ENVIRONMENT=DEV
LOG_LEVEL=info
# Database (required for auth and content-db features)
DATABASE_URL=postgres://username:password@localhost:5432/rustelo_dev
# TLS configuration (required when using https protocol)
TLS_CERT_PATH=./certs/cert.pem
TLS_KEY_PATH=./certs/key.pem
# JWT configuration (for auth feature)
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_EXPIRATION_HOURS=24
# OAuth providers (for auth feature)
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 (for auth feature)
TOTP_ISSUER=Rustelo
TOTP_SERVICE_NAME=Rustelo Authentication
# Content configuration (for content-db feature)
CONTENT_CACHE_ENABLED=true
CONTENT_CACHE_TTL=3600
```
## Docker Configuration
For containerized deployments, you can use build arguments:
```dockerfile
# Build with specific features
ARG FEATURES="tls,auth,content-db"
RUN cargo build --release --features ${FEATURES}
```
## Development vs Production
### Development
```bash
# Development with all features
cargo run
# Development without TLS
cargo run --no-default-features --features "auth,content-db"
```
### Production
```bash
# Production build with TLS
cargo build --release --features "tls,auth,content-db"
# Set production environment
ENVIRONMENT=PROD SERVER_PROTOCOL=https ./target/release/server
```
## Feature Detection at Runtime
The application will log which features are enabled at startup:
```
INFO Server starting on 127.0.0.1:3030
INFO Environment: Development
INFO Security features enabled: CSRF, Rate Limiting, Security Headers
INFO Authentication endpoints available at: /api/auth/*
INFO Content management endpoints available at: /api/content/*
INFO OAuth providers configured: ["google", "github"]
```
If features are disabled, you'll see:
```
INFO Authentication disabled - no auth endpoints available
INFO Database content disabled - using static content only
```
## Migration Guide
### Disabling Authentication
If you want to disable authentication in an existing project:
1. Remove `auth` from default features in `Cargo.toml`
2. Remove authentication-related environment variables
3. Remove database tables if not using `content-db`
### Disabling Database Content
If you want to switch to static content only:
1. Remove `content-db` from default features in `Cargo.toml`
2. Place your content files in the `content/` directory
3. Update your content loading logic to use file-based content
### Adding TLS
To add TLS support to an existing deployment:
1. Add `tls` feature to your build command
2. Obtain SSL certificates
3. Set `SERVER_PROTOCOL=https` and certificate paths
4. Update your reverse proxy configuration if applicable
## Troubleshooting
### Common Issues
**TLS Certificate Errors:**
- Ensure certificate files exist at the specified paths
- Check certificate format (PEM expected)
- Verify certificate chain completeness
**Database Connection Issues:**
- Verify DATABASE_URL format
- Check database server availability
- Ensure database exists and user has permissions
**OAuth Configuration:**
- Verify client IDs and secrets
- Check OAuth provider redirect URLs
- Ensure proper scopes are configured
### Feature Compilation Errors
If you encounter compilation errors:
1. Check that all required dependencies are available
2. Verify feature combinations are valid
3. Ensure environment variables are set correctly
4. Check that conditional compilation blocks match your feature selection
## Security Considerations
- Always use TLS in production environments
- Rotate JWT secrets regularly
- Use strong OAuth client secrets
- Enable 2FA for sensitive applications
- Regularly update dependencies
- Monitor authentication logs
- Use environment-specific configurations
## Performance Considerations
- Enable content caching for better performance
- Consider database connection pooling
- Use appropriate log levels in production
- Monitor memory usage with enabled features
- Consider feature combinations based on your needs

394
book/features/overview.md
View File

@ -1,394 +0,0 @@
# Features Overview
<div align="center">
<img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
</div>
Rustelo is built around a modular feature system that allows you to enable only the functionality you need. This approach keeps your application lean, reduces compile times, and ensures you're not carrying unnecessary dependencies.
## Philosophy
The feature system is designed with these principles in mind:
- **🎯 Opt-in by Design**: Start minimal and add features as needed
- **🔧 Zero Configuration**: Features work out of the box with sensible defaults
- **📦 Minimal Dependencies**: Each feature only includes what it absolutely needs
- **🔄 Composable**: Features work together seamlessly
- **🛡️ Secure by Default**: Security considerations built into every feature
## Feature Categories
### Core Features (Always Available)
These features are always available regardless of your configuration:
- **Static File Serving**: Serve static assets (CSS, JS, images)
- **Routing**: Client-side and server-side routing
- **CSRF Protection**: Cross-site request forgery protection
- **Security Headers**: Basic security headers
- **Rate Limiting**: Basic rate limiting
- **Health Checks**: System health monitoring endpoints
- **Logging**: Structured logging with tracing
### Optional Features
#### 🔐 Authentication (`auth`)
**Default: Enabled**
Complete user authentication and authorization system.
**What it provides:**
- JWT token-based authentication
- OAuth2 integration (Google, GitHub, etc.)
- Two-factor authentication (2FA/TOTP)
- Password hashing with Argon2
- Session management
- User registration and login
- Password reset functionality
- Role-based access control (RBAC)
**Use cases:**
- User portals and dashboards
- SaaS applications
- Protected content areas
- Multi-tenant applications
**Dependencies:**
- `jsonwebtoken` - JWT handling
- `argon2` - Secure password hashing
- `oauth2` - OAuth2 client implementation
- `totp-rs` - Two-factor authentication
- `qrcode` - QR code generation
- `tower-sessions` - Session management
#### 📄 Content Management (`content-db`)
**Default: Enabled**
Database-driven content management with Markdown support.
**What it provides:**
- Markdown content rendering
- Syntax highlighting for code blocks
- YAML frontmatter support
- Content caching system
- Dynamic content loading
- Content versioning
- SEO-friendly URLs
- Full-text search capabilities
**Use cases:**
- Blogs and news sites
- Documentation sites
- Content management systems
- Marketing websites
- Knowledge bases
**Dependencies:**
- `pulldown-cmark` - Markdown parsing
- `syntect` - Syntax highlighting
- `serde_yaml` - YAML frontmatter
- `sqlx` - Database access
#### 🔒 TLS Support (`tls`)
**Default: Disabled**
HTTPS/TLS encryption for secure connections.
**What it provides:**
- HTTPS server support
- TLS certificate management
- Automatic HTTP to HTTPS redirects
- SSL/TLS configuration
- Certificate validation
- Support for Let's Encrypt certificates
**Use cases:**
- Production deployments
- Security-sensitive applications
- Compliance requirements
- E-commerce applications
**Dependencies:**
- `axum-server` - TLS-enabled server
- `rustls` - Pure Rust TLS implementation
- `rustls-pemfile` - Certificate file handling
#### 📧 Email System (`email`)
**Default: Enabled**
Comprehensive email functionality with multiple providers.
**What it provides:**
- Multiple email providers (SMTP, SendGrid, AWS SES)
- HTML and text email templates
- Contact form handling
- Email verification
- Password reset emails
- Notification system
- Email queue management
- Bounce handling
**Use cases:**
- Contact forms
- User notifications
- Marketing emails
- Transactional emails
- Newsletter systems
**Dependencies:**
- `lettre` - Email sending
- `handlebars` - Email templating
- `urlencoding` - URL encoding
- `async-trait` - Async trait support
## Feature Combinations
### Common Combinations
#### Minimal Static Site
```bash
cargo build --no-default-features
```
**Perfect for:**
- Marketing websites
- Landing pages
- Documentation sites
- Portfolio sites
**Features included:**
- Static file serving
- Basic routing
- Security headers
#### Secure Static Site
```bash
cargo build --no-default-features --features "tls"
```
**Perfect for:**
- Production static sites
- Security-conscious deployments
- Compliance requirements
**Features included:**
- All minimal features
- HTTPS/TLS support
#### Authentication-Only App
```bash
cargo build --no-default-features --features "auth"
```
**Perfect for:**
- User portals
- Dashboard applications
- API services with authentication
**Features included:**
- User management
- JWT authentication
- OAuth2 providers
- Session management
#### Content Management System
```bash
cargo build --no-default-features --features "content-db"
```
**Perfect for:**
- Blogs
- News sites
- Documentation platforms
- Knowledge bases
**Features included:**
- Markdown rendering
- Database content storage
- Content caching
#### Communication Site
```bash
cargo build --no-default-features --features "email"
```
**Perfect for:**
- Contact pages
- Feedback forms
- Newsletter signups
- Notification systems
**Features included:**
- Email sending
- Form handling
- Template system
#### Full-Featured Application
```bash
cargo build --features "auth,content-db,email"
# or simply: cargo build (uses defaults)
```
**Perfect for:**
- Complete web applications
- SaaS platforms
- User-generated content sites
- E-commerce applications
**Features included:**
- Complete user management
- Content management
- Email system
- All security features
#### Production-Ready
```bash
cargo build --release --features "tls,auth,content-db,email"
```
**Perfect for:**
- Production deployments
- Enterprise applications
- High-security requirements
**Features included:**
- All features enabled
- HTTPS/TLS security
- Optimized for performance
## Configuration Matrix
| Feature | Database Required | Email Required | TLS Recommended |
|---------|------------------|----------------|-----------------|
| Static Site | ❌ | ❌ | ✅ (Production) |
| Auth | ✅ | ✅ (Password Reset) | ✅ |
| Content-DB | ✅ | ❌ | ✅ (Production) |
| Email | ❌ | ✅ | ✅ (Production) |
| TLS | ❌ | ❌ | N/A |
## Performance Impact
### Build Times
- **Minimal**: ~30 seconds
- **Auth Only**: ~45 seconds
- **Content-DB Only**: ~40 seconds
- **Full Featured**: ~60 seconds
### Binary Size
- **Minimal**: ~2MB
- **Auth Only**: ~5MB
- **Content-DB Only**: ~4MB
- **Full Featured**: ~8MB
### Memory Usage
- **Minimal**: ~10MB RAM
- **Auth Only**: ~25MB RAM
- **Content-DB Only**: ~20MB RAM
- **Full Featured**: ~40MB RAM
### Cold Start Time
- **Minimal**: ~50ms
- **Auth Only**: ~200ms
- **Content-DB Only**: ~150ms
- **Full Featured**: ~300ms
## Feature Dependencies
### Database Features
Features that require database access:
- `auth` - User accounts, sessions, OAuth tokens
- `content-db` - Content storage, caching, search
### Email Features
Features that benefit from email:
- `auth` - Password reset, email verification
- `email` - Contact forms, notifications
### Security Features
Features that enhance security:
- `tls` - HTTPS encryption
- `auth` - User authentication
- All features include basic security (CSRF, rate limiting, headers)
## Development vs Production
### Development Recommendations
```bash
# Fast development cycle
cargo build --features "auth,content-db,email"
# With hot reloading
cargo leptos serve --features "auth,content-db,email"
```
### Production Recommendations
```bash
# Secure production build
cargo build --release --features "tls,auth,content-db,email"
# Minimal production (static sites)
cargo build --release --no-default-features --features "tls"
```
## Migration Between Features
### Adding Features
1. Update feature flags in build command
2. Add required environment variables
3. Run database migrations (if applicable)
4. Update frontend components
5. Test thoroughly
### Removing Features
1. Export/backup relevant data
2. Update feature flags
3. Remove unused environment variables
4. Clean up unused code
5. Test reduced functionality
## Feature Roadmap
### Planned Features
- **WebSocket Support**: Real-time communication
- **File Upload**: File management system
- **Admin Dashboard**: Administrative interface
- **API Documentation**: Automatic API docs
- **Metrics & Monitoring**: Application metrics
- **Search Engine**: Full-text search
- **Caching Layer**: Redis integration
- **Message Queue**: Background job processing
### Experimental Features
- **GraphQL API**: Alternative to REST
- **Server-Side Events**: Real-time updates
- **Multi-tenancy**: Tenant isolation
- **Audit Logging**: Comprehensive audit trails
## Best Practices
### Feature Selection
1. **Start Minimal**: Begin with only essential features
2. **Add Gradually**: Introduce features as requirements evolve
3. **Consider Dependencies**: Understand feature interactions
4. **Test Combinations**: Verify feature combinations work together
5. **Document Choices**: Record why features were selected
### Configuration
1. **Environment-Specific**: Use different features per environment
2. **Feature Flags**: Use runtime feature flags for A/B testing
3. **Graceful Degradation**: Handle missing features gracefully
4. **Monitoring**: Monitor feature usage and performance
### Development
1. **Feature Branches**: Develop features in isolation
2. **Integration Testing**: Test feature combinations
3. **Documentation**: Document feature usage
4. **Performance Testing**: Measure feature impact
## Next Steps
Ready to dive deeper into specific features? Check out:
- **[Authentication System](./authentication.md)** - Complete user management
- **[Content Management](./content-management.md)** - Database-driven content
- **[TLS Support](./tls.md)** - HTTPS configuration
- **[Email System](./email.md)** - Communication features
- **[Feature Combinations](./combinations.md)** - Detailed combination guide
Or explore the technical details:
- **[Database Overview](../database/overview.md)** - Database configuration
- **[Security Overview](../security/overview.md)** - Security features
- **[Performance Overview](../performance/overview.md)** - Performance considerations

0
book/features/tls.md
View File

444
book/getting-started/configuration.md
View File

@ -1,444 +0,0 @@
# Basic Configuration
<div align="center">
<img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
</div>
Welcome to Rustelo's configuration system! This guide will help you get started with configuring your Rustelo application for different environments and use cases.
## Overview
Rustelo uses a powerful, modular configuration system that allows you to:
- Configure different settings for development, staging, and production
- Enable or disable features based on your needs
- Manage secrets securely through environment variables
- Build complete configurations from modular components
## Quick Start
### 1. Build Your First Configuration
The easiest way to get started is to build a development configuration:
```bash
# Navigate to your Rustelo project
cd your-rustelo-project
# Build development configuration
./config/scripts/build-config.sh dev
```
This creates a `config.toml` file with all the settings needed for development.
### 2. Environment Variables
Set up your basic environment variables:
```bash
# Create a .env file for development
cat > .env << EOF
DATABASE_URL=sqlite//:dev_database.db
SESSION_SECRET=your-development-session-secret
JWT_SECRET=your-development-jwt-secret
EOF
```
### 3. Start Your Application
With your configuration in place, you can start your application:
```bash
# Load environment variables and start
source .env
cargo run --bin server
```
## Configuration Structure
Rustelo's configuration is built from two main components:
### Base Configuration
Base configurations contain core settings that apply to all features:
- **Server settings**: Host, port, workers
- **Database settings**: Connection URL, pool size
- **Security settings**: CSRF protection, rate limiting
- **Session management**: Cookie settings, timeouts
### Feature Configuration
Feature configurations contain settings specific to individual features:
- **Authentication**: JWT settings, password policies, OAuth
- **Email**: SMTP configuration, templates, providers
- **Content**: Markdown processing, file uploads, search
- **Metrics**: Monitoring, alerts, dashboards
- **TLS**: SSL certificates, cipher suites, security headers
## Available Environments
Rustelo comes with three pre-configured environments:
### Development (`dev`)
- Optimized for developer experience
- Relaxed security settings
- Verbose logging
- SQLite database by default
- Hot reloading enabled
```bash
./config/scripts/build-config.sh dev
```
### Production (`prod`)
- Optimized for performance and security
- Strict security settings
- Minimal logging
- PostgreSQL database recommended
- Monitoring enabled
```bash
./config/scripts/build-config.sh prod config.prod.toml
```
### Example (`example`)
- Complete documentation of all options
- Best practice configurations
- Commented examples for learning
```bash
./config/scripts/build-config.sh example config.example.toml
```
## Essential Configuration Options
### Database Configuration
Choose your database backend:
```toml
[database]
# SQLite (great for development)
url = "sqlite://database.db"
# PostgreSQL (recommended for production)
url = "postgresql://user:password@localhost:5432/myapp"
```
### Server Configuration
Configure your web server:
```toml
[server]
host = "127.0.0.1" # Development
# host = "0.0.0.0" # Production
port = 3030
workers = 1 # Development
# workers = 4 # Production
```
### Feature Enablement
Enable the features you need:
```toml
[features]
auth = true # User authentication
content = true # Content management
email = false # Email system (requires SMTP setup)
metrics = true # Monitoring and metrics
tls = false # SSL/TLS (enable for production)
```
## Environment Variables
Rustelo uses environment variables for sensitive configuration:
### Required Variables
For development:
```bash
DATABASE_URL=sqlite://dev_database.db # Optional, has default
SESSION_SECRET=your-session-secret # Required
```
For production:
```bash
DATABASE_URL=postgresql://user:pass@host/db # Required
SESSION_SECRET=your-secure-session-secret # Required (32+ chars)
JWT_SECRET=your-secure-jwt-secret # Required (32+ chars)
DOMAIN=yourapp.com # Required for cookies
FRONTEND_URL=https://yourapp.com # Required for CORS
```
### Optional Variables
Email configuration (if email feature enabled):
```bash
SMTP_HOST=smtp.gmail.com
SMTP_USERNAME=your-app@gmail.com
SMTP_PASSWORD=your-app-password
FROM_EMAIL=noreply@yourapp.com
```
TLS configuration (if TLS feature enabled):
```bash
TLS_CERT_FILE=/etc/ssl/certs/yourapp.crt
TLS_KEY_FILE=/etc/ssl/private/yourapp.key
```
## Feature Configuration Examples
### Authentication Setup
Enable authentication with basic settings:
```toml
[features]
auth = true
[auth.jwt]
secret = "${JWT_SECRET}"
expiration = 3600 # 1 hour
[auth.password]
min_length = 8
require_numbers = true
```
### Email Setup
Configure email for notifications:
```toml
[features]
email = true
[email]
provider = "smtp"
from_email = "${FROM_EMAIL}"
[email.smtp]
host = "${SMTP_HOST}"
port = 587
username = "${SMTP_USERNAME}"
password = "${SMTP_PASSWORD}"
use_tls = true
```
### Content Management
Enable content features:
```toml
[features]
content = true
[content]
enabled = true
max_file_size = 10485760 # 10MB
allowed_file_types = ["jpg", "png", "pdf", "md"]
[content.markdown]
enabled = true
syntax_highlighting = true
```
## Configuration Management
### List Available Features
See what features are available:
```bash
./config/scripts/debug-manage.sh list-features
```
### Check Configuration Status
Review your current configuration:
```bash
./config/scripts/debug-manage.sh status
```
### Compare Environments
Compare settings between environments:
```bash
# Build both configurations first
./config/scripts/build-config.sh dev config.dev.toml
./config/scripts/build-config.sh prod config.prod.toml
# Compare them
diff config.dev.toml config.prod.toml
```
### Backup Configurations
Backup your current configuration:
```bash
cp config.toml config.backup.toml
```
## Common Configuration Patterns
### Development Setup
For local development:
```bash
# Set environment
export RUSTELO_ENV=development
# Simple database
export DATABASE_URL=sqlite://dev_database.db
# Basic auth secrets
export SESSION_SECRET=dev-session-secret
export JWT_SECRET=dev-jwt-secret
# Build config
./config/scripts/build-config.sh dev
```
### Production Setup
For production deployment:
```bash
# Set environment
export RUSTELO_ENV=production
# Production database
export DATABASE_URL=postgresql://user:password@db:5432/app
# Secure secrets (use a secret manager in real deployments)
export SESSION_SECRET=$(openssl rand -base64 32)
export JWT_SECRET=$(openssl rand -base64 32)
# Domain configuration
export DOMAIN=yourapp.com
export FRONTEND_URL=https://yourapp.com
# Build config
./config/scripts/build-config.sh prod config.prod.toml
```
### Docker Setup
For containerized deployment:
```dockerfile
FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN ./config/scripts/build-config.sh prod config.prod.toml
RUN cargo build --release
FROM debian:bookworm-slim
COPY --from=builder /app/target/release/server /usr/local/bin/
COPY --from=builder /app/config.prod.toml /etc/rustelo/config.toml
ENV RUSTELO_CONFIG_FILE=/etc/rustelo/config.toml
EXPOSE 3030
CMD ["server"]
```
## Troubleshooting
### Configuration Build Fails
If configuration building fails:
1. Check that all required files exist:
```bash
ls -la config/base/
ls -la config/features/
```
2. Validate individual files:
```bash
# Check base configuration
cat config/base/dev.toml
# Check feature configurations
cat config/features/auth/dev.toml
```
3. Check for syntax errors:
```bash
# Install TOML validator (optional)
cargo install toml-cli
# Validate syntax
toml get config/base/dev.toml
```
### Missing Environment Variables
If you get errors about missing environment variables:
1. Check required variables are set:
```bash
echo $DATABASE_URL
echo $SESSION_SECRET
echo $JWT_SECRET
```
2. Create a .env file:
```bash
cat > .env << EOF
DATABASE_URL=sqlite:dev_database.db
SESSION_SECRET=your-session-secret
JWT_SECRET=your-jwt-secret
EOF
# Load environment
source .env
```
### Application Won't Start
If the application fails to start:
1. Check configuration file exists:
```bash
ls -la config.toml
```
2. Validate configuration:
```bash
./config/scripts/debug-manage.sh status
```
3. Check logs for specific errors:
```bash
cargo run --bin server 2>&1 | head -20
```
## Next Steps
Now that you have basic configuration working:
1. **Explore Features**: Learn about [Features Configuration](../configuration/features.md)
2. **Security Setup**: Review [Security Settings](../configuration/security.md)
3. **Environment Variables**: Deep dive into [Environment Variables](../configuration/environment.md)
4. **Production Deployment**: Check out [Production Setup](../deployment/production.md)
5. **Performance Tuning**: Optimize with [Performance Configuration](../configuration/performance.md)
## Getting Help
If you need assistance with configuration:
- Check the [Troubleshooting Guide](../troubleshooting/common.md)
- Review the [Configuration Files Guide](../configuration/files.md)
- Look at example configurations in `config/features/*/example.toml`
- Ask questions in the community forums
The configuration system is designed to be flexible and powerful while remaining approachable for new users. Start simple and add complexity as your needs grow!

825
book/getting-started/first-app.md
View File

@ -1,825 +0,0 @@
# Building Your First Rustelo Application
<div align="center">
<img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
</div>
<div align="center">
<img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
</div>
Welcome to building your first[Rustelo](/)application! This guide will walk you through creating a complete web application from scratch, covering both frontend and backend development with Rustelo's powerful features.
## 🎯 What You'll Build
By the end of this guide, you'll have created a **Task Management Application** with:
- 📝 **Frontend**: Interactive task list with Leptos components
- 🔧 **Backend**: RESTful API with Axum server
- 🗄️ **Database**: Data persistence with SQLx
- 🔐 **Authentication**: User login and registration
- 🎨 **Styling**: Modern UI with Tailwind CSS
- 📱 **Responsive**: Mobile-friendly design
## 🚀 Prerequisites
Before starting, ensure you have:
- ✅ **Rustelo installed** - Follow the [Installation Guide](./installation.md)
- ✅ **Basic Rust knowledge** - Variables, structs, functions
- ✅ **Web development basics** - HTML, CSS, HTTP concepts
- ✅ **Development environment** - Your favorite code editor
## 📋 Step 1: Project Setup
### Create Your Project
```bash
# Clone the[Rustelo](/) template
git clone https://github.com/yourusername/rustelo.git my-task-app
cd my-task-app
# Run the installer
./scripts/install.sh
```
### Configure Your Application
```bash
# Set up environment variables
cat > .env << EOF
# Database Configuration
DATABASE_URL=sqlite//:tasks.db
# Security Configuration
SESSION_SECRET=your-development-session-secret-here
JWT_SECRET=your-development-jwt-secret-here
# Application Configuration
RUSTELO_ENV=development
SERVER_HOST=127.0.0.1
SERVER_PORT=3030
LOG_LEVEL=debug
# Features Configuration
ENABLE_AUTH=true
ENABLE_CONTENT_DB=true
ENABLE_EMAIL=false
ENABLE_TLS=false
EOF
```
### Build Your Configuration
```bash
# Build development configuration
./config/scripts/build-config.sh dev
# Verify setup
just verify-setup
```
## 🏗️ Step 2: Database Schema
### Create Database Migration
```bash
# Create migration for tasks table
sqlx migrate add create_tasks_table
```
Edit the migration file in `migrations/`:
```sql
-- migrations/001_create_tasks_table.sql
CREATE TABLE IF NOT EXISTS tasks (
id INTEGER PRIMARY KEY AUTOINCREMENT,
title TEXT NOT NULL,
description TEXT,
completed BOOLEAN NOT NULL DEFAULT FALSE,
priority INTEGER NOT NULL DEFAULT 1,
due_date TEXT,
created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
user_id INTEGER,
FOREIGN KEY (user_id) REFERENCES users(id)
);
-- Index for faster queries
CREATE INDEX IF NOT EXISTS idx_tasks_user_id ON tasks(user_id);
CREATE INDEX IF NOT EXISTS idx_tasks_completed ON tasks(completed);
```
### Run Migration
```bash
# Apply database migrations
just db-migrate
# Verify database structure
just db-status
```
## 🔧 Step 3: Shared Types
Create shared data structures in `shared/src/types.rs`:
```rust
// shared/src/types.rs
use serde::{Deserialize, Serialize};
use chrono::{DateTime, Utc};
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Task {
pub id: Option<i32>,
pub title: String,
pub description: Option<String>,
pub completed: bool,
pub priority: TaskPriority,
pub due_date: Option<DateTime<Utc>>,
pub created_at: DateTime<Utc>,
pub updated_at: DateTime<Utc>,
pub user_id: Option<i32>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub enum TaskPriority {
Low = 1,
Medium = 2,
High = 3,
Urgent = 4,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct CreateTaskRequest {
pub title: String,
pub description: Option<String>,
pub priority: TaskPriority,
pub due_date: Option<DateTime<Utc>>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UpdateTaskRequest {
pub title: Option<String>,
pub description: Option<String>,
pub completed: Option<bool>,
pub priority: Option<TaskPriority>,
pub due_date: Option<DateTime<Utc>>,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct TasksResponse {
pub tasks: Vec<Task>,
pub total: usize,
pub page: usize,
pub per_page: usize,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ApiResponse<T> {
pub success: bool,
pub data: Option<T>,
pub message: Option<String>,
}
```
Update `shared/src/lib.rs`:
```rust
// shared/src/lib.rs
pub mod types;
pub mod utils;
pub use types::*;
```
## 🖥️ Step 4: Backend API
### Create Task Repository
Create `server/src/repositories/task_repository.rs`:
```rust
// server/src/repositories/task_repository.rs
use sqlx::{SqlitePool, Row};
use chrono::{DateTime, Utc};
use shared::{Task, CreateTaskRequest, UpdateTaskRequest, TaskPriority};
use anyhow::Result;
pub struct TaskRepository {
pool: SqlitePool,
}
impl TaskRepository {
pub fn new(pool: SqlitePool) -> Self {
Self { pool }
}
pub async fn create_task(&self, request: CreateTaskRequest, user_id: i32) -> Result<Task> {
let now = Utc::now();
let row = sqlx::query!(
r#"
INSERT INTO tasks (title, description, priority, due_date, created_at, updated_at, user_id)
VALUES (?, ?, ?, ?, ?, ?, ?)
RETURNING id, title, description, completed, priority, due_date, created_at, updated_at, user_id
"#,
request.title,
request.description,
request.priority as i32,
request.due_date.map(|d| d.to_rfc3339()),
now.to_rfc3339(),
now.to_rfc3339(),
user_id
)
.fetch_one(&self.pool)
.await?;
Ok(Task {
id: Some(row.id),
title: row.title,
description: row.description,
completed: row.completed,
priority: match row.priority {
1 => TaskPriority::Low,
2 => TaskPriority::Medium,
3 => TaskPriority::High,
4 => TaskPriority::Urgent,
_ => TaskPriority::Medium,
},
due_date: row.due_date.and_then(|d| DateTime::parse_from_rfc3339(&d).ok())
.map(|d| d.with_timezone(&Utc)),
created_at: DateTime::parse_from_rfc3339(&row.created_at).unwrap().with_timezone(&Utc),
updated_at: DateTime::parse_from_rfc3339(&row.updated_at).unwrap().with_timezone(&Utc),
user_id: Some(row.user_id),
})
}
pub async fn get_tasks_by_user(&self, user_id: i32, page: usize, per_page: usize) -> Result<Vec<Task>> {
let offset = (page - 1) * per_page;
let rows = sqlx::query!(
r#"
SELECT id, title, description, completed, priority, due_date, created_at, updated_at, user_id
FROM tasks
WHERE user_id = ?
ORDER BY created_at DESC
LIMIT ? OFFSET ?
"#,
user_id,
per_page as i32,
offset as i32
)
.fetch_all(&self.pool)
.await?;
let tasks = rows.into_iter().map(|row| Task {
id: Some(row.id),
title: row.title,
description: row.description,
completed: row.completed,
priority: match row.priority {
1 => TaskPriority::Low,
2 => TaskPriority::Medium,
3 => TaskPriority::High,
4 => TaskPriority::Urgent,
_ => TaskPriority::Medium,
},
due_date: row.due_date.and_then(|d| DateTime::parse_from_rfc3339(&d).ok())
.map(|d| d.with_timezone(&Utc)),
created_at: DateTime::parse_from_rfc3339(&row.created_at).unwrap().with_timezone(&Utc),
updated_at: DateTime::parse_from_rfc3339(&row.updated_at).unwrap().with_timezone(&Utc),
user_id: Some(row.user_id),
}).collect();
Ok(tasks)
}
pub async fn update_task(&self, task_id: i32, request: UpdateTaskRequest, user_id: i32) -> Result<Task> {
// First check if task exists and belongs to user
let existing = sqlx::query!(
"SELECT id FROM tasks WHERE id = ? AND user_id = ?",
task_id,
user_id
)
.fetch_optional(&self.pool)
.await?;
if existing.is_none() {
return Err(anyhow::anyhow!("Task not found or access denied"));
}
let now = Utc::now();
// Build dynamic update query
let mut update_fields = Vec::new();
let mut params: Vec<&dyn sqlx::Encode<'_, sqlx::Sqlite>> = Vec::new();
if let Some(title) = &request.title {
update_fields.push("title = ?");
params.push(title);
}
if let Some(description) = &request.description {
update_fields.push("description = ?");
params.push(description);
}
if let Some(completed) = &request.completed {
update_fields.push("completed = ?");
params.push(completed);
}
if let Some(priority) = &request.priority {
update_fields.push("priority = ?");
let priority_val = *priority as i32;
params.push(&priority_val);
}
if let Some(due_date) = &request.due_date {
update_fields.push("due_date = ?");
let due_date_str = due_date.to_rfc3339();
params.push(&due_date_str);
}
if update_fields.is_empty() {
return Err(anyhow::anyhow!("No fields to update"));
}
update_fields.push("updated_at = ?");
let now_str = now.to_rfc3339();
params.push(&now_str);
let query = format!(
"UPDATE tasks SET {} WHERE id = ? AND user_id = ?",
update_fields.join(", ")
);
// Execute update
sqlx::query(&query)
.bind(task_id)
.bind(user_id)
.execute(&self.pool)
.await?;
// Return updated task
let row = sqlx::query!(
r#"
SELECT id, title, description, completed, priority, due_date, created_at, updated_at, user_id
FROM tasks
WHERE id = ?
"#,
task_id
)
.fetch_one(&self.pool)
.await?;
Ok(Task {
id: Some(row.id),
title: row.title,
description: row.description,
completed: row.completed,
priority: match row.priority {
1 => TaskPriority::Low,
2 => TaskPriority::Medium,
3 => TaskPriority::High,
4 => TaskPriority::Urgent,
_ => TaskPriority::Medium,
},
due_date: row.due_date.and_then(|d| DateTime::parse_from_rfc3339(&d).ok())
.map(|d| d.with_timezone(&Utc)),
created_at: DateTime::parse_from_rfc3339(&row.created_at).unwrap().with_timezone(&Utc),
updated_at: DateTime::parse_from_rfc3339(&row.updated_at).unwrap().with_timezone(&Utc),
user_id: Some(row.user_id),
})
}
pub async fn delete_task(&self, task_id: i32, user_id: i32) -> Result<bool> {
let result = sqlx::query!(
"DELETE FROM tasks WHERE id = ? AND user_id = ?",
task_id,
user_id
)
.execute(&self.pool)
.await?;
Ok(result.rows_affected() > 0)
}
pub async fn count_tasks_by_user(&self, user_id: i32) -> Result<usize> {
let row = sqlx::query!(
"SELECT COUNT(*) as count FROM tasks WHERE user_id = ?",
user_id
)
.fetch_one(&self.pool)
.await?;
Ok(row.count as usize)
}
}
```
### Create API Handlers
Create `server/src/handlers/task_handlers.rs`:
```rust
// server/src/handlers/task_handlers.rs
use axum::{
extract::{Path, Query, State},
response::Json,
http::StatusCode,
};
use serde::{Deserialize, Serialize};
use shared::{CreateTaskRequest, UpdateTaskRequest, TasksResponse, ApiResponse};
use crate::{
repositories::task_repository::TaskRepository,
auth::AuthUser,
AppState,
};
#[derive(Debug, Deserialize)]
pub struct TaskQuery {
pub page: Option<usize>,
pub per_page: Option<usize>,
}
pub async fn create_task(
State(state): State<AppState>,
AuthUser(user_id): AuthUser,
Json(request): Json<CreateTaskRequest>,
) -> Result<Json<ApiResponse<shared::Task>>, StatusCode> {
let task_repo = TaskRepository::new(state.db_pool.clone());
match task_repo.create_task(request, user_id).await {
Ok(task) => Ok(Json(ApiResponse {
success: true,
data: Some(task),
message: Some("Task created successfully".to_string()),
})),
Err(e) => {
tracing::error!("Failed to create task: {}", e);
Err(StatusCode::INTERNAL_SERVER_ERROR)
}
}
}
pub async fn get_tasks(
State(state): State<AppState>,
AuthUser(user_id): AuthUser,
Query(params): Query<TaskQuery>,
) -> Result<Json<ApiResponse<TasksResponse>>, StatusCode> {
let task_repo = TaskRepository::new(state.db_pool.clone());
let page = params.page.unwrap_or(1);
let per_page = params.per_page.unwrap_or(10).min(100); // Limit to 100 per page
match task_repo.get_tasks_by_user(user_id, page, per_page).await {
Ok(tasks) => {
let total = task_repo.count_tasks_by_user(user_id).await.unwrap_or(0);
let response = TasksResponse {
tasks,
total,
page,
per_page,
};
Ok(Json(ApiResponse {
success: true,
data: Some(response),
message: None,
}))
}
Err(e) => {
tracing::error!("Failed to get tasks: {}", e);
Err(StatusCode::INTERNAL_SERVER_ERROR)
}
}
}
pub async fn update_task(
State(state): State<AppState>,
AuthUser(user_id): AuthUser,
Path(task_id): Path<i32>,
Json(request): Json<UpdateTaskRequest>,
) -> Result<Json<ApiResponse<shared::Task>>, StatusCode> {
let task_repo = TaskRepository::new(state.db_pool.clone());
match task_repo.update_task(task_id, request, user_id).await {
Ok(task) => Ok(Json(ApiResponse {
success: true,
data: Some(task),
message: Some("Task updated successfully".to_string()),
})),
Err(e) => {
tracing::error!("Failed to update task: {}", e);
if e.to_string().contains("not found") {
Err(StatusCode::NOT_FOUND)
} else {
Err(StatusCode::INTERNAL_SERVER_ERROR)
}
}
}
}
pub async fn delete_task(
State(state): State<AppState>,
AuthUser(user_id): AuthUser,
Path(task_id): Path<i32>,
) -> Result<Json<ApiResponse<()>>, StatusCode> {
let task_repo = TaskRepository::new(state.db_pool.clone());
match task_repo.delete_task(task_id, user_id).await {
Ok(true) => Ok(Json(ApiResponse {
success: true,
data: None,
message: Some("Task deleted successfully".to_string()),
})),
Ok(false) => Err(StatusCode::NOT_FOUND),
Err(e) => {
tracing::error!("Failed to delete task: {}", e);
Err(StatusCode::INTERNAL_SERVER_ERROR)
}
}
}
```
### Update API Routes
Update `server/src/main.rs` to include task routes:
```rust
// Add to server/src/main.rs
use axum::{
routing::{get, post, put, delete},
Router,
};
mod handlers;
mod repositories;
use handlers::task_handlers::*;
// In your app router setup:
pub fn api_routes() -> Router<AppState> {
Router::new()
.route("/api/tasks", post(create_task))
.route("/api/tasks", get(get_tasks))
.route("/api/tasks/:id", put(update_task))
.route("/api/tasks/:id", delete(delete_task))
// ... other routes
}
```
## 🎨 Step 5: Frontend Components
### Create Task Components
Create `client/src/components/tasks/task_item.rs`:
```rust
// client/src/components/tasks/task_item.rs
use leptos::prelude::*;
use shared::{Task, TaskPriority};
use chrono::{DateTime, Utc};
#[component]
pub fn TaskItem(
task: Task,
#[prop(into)] on_toggle: Callback<i32>,
#[prop(into)] on_delete: Callback<i32>,
#[prop(into)] on_edit: Callback<Task>,
) -> impl IntoView {
let task_id = task.id.unwrap_or(0);
let is_completed = task.completed;
let is_overdue = task.due_date
.map(|due| due < Utc::now() && !task.completed)
.unwrap_or(false);
let priority_class = match task.priority {
TaskPriority::Low => "border-l-green-400",
TaskPriority::Medium => "border-l-yellow-400",
TaskPriority::High => "border-l-orange-400",
TaskPriority::Urgent => "border-l-red-400",
};
let priority_text = match task.priority {
TaskPriority::Low => "Low",
TaskPriority::Medium => "Medium",
TaskPriority::High => "High",
TaskPriority::Urgent => "Urgent",
};
view! {
<div class=format!(
"bg-white rounded-lg shadow-sm border-l-4 {} p-4 mb-3 transition-all duration-200 hover:shadow-md",
priority_class
)>
<div class="flex items-start justify-between">
<div class="flex items-start space-x-3 flex-1">
<input
type="checkbox"
checked=is_completed
class="mt-1 h-4 w-4 text-blue-600 focus:ring-blue-500 border-gray-300 rounded"
on:change=move |_| on_toggle(task_id)
/>
<div class="flex-1">
<h3 class=format!(
"text-lg font-medium {} {}",
if is_completed { "line-through text-gray-500" } else { "text-gray-900" },
if is_overdue { "text-red-600" } else { "" }
)>
{task.title.clone()}
</h3>
{task.description.clone().map(|desc| view! {
<p class="mt-1 text-gray-600 text-sm">{desc}</p>
})}
<div class="flex items-center space-x-4 mt-2 text-sm text-gray-500">
<span class=format!(
"px-2 py-1 rounded-full text-xs font-medium {}",
match task.priority {
TaskPriority::Low => "bg-green-100 text-green-800",
TaskPriority::Medium => "bg-yellow-100 text-yellow-800",
TaskPriority::High => "bg-orange-100 text-orange-800",
TaskPriority::Urgent => "bg-red-100 text-red-800",
}
)>
{priority_text}
</span>
{task.due_date.map(|due| {
let due_str = due.format("%Y-%m-%d %H:%M").to_string();
view! {
<span class=format!(
"{}",
if is_overdue { "text-red-600 font-medium" } else { "" }
)>
"Due: " {due_str}
</span>
}
})}
</div>
</div>
</div>
<div class="flex items-center space-x-2">
<button
class="text-gray-400 hover:text-blue-600 transition-colors"
on:click=move |_| on_edit(task.clone())
title="Edit task"
>
<svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z"/>
</svg>
</button>
<button
class="text-gray-400 hover:text-red-600 transition-colors"
on:click=move |_| on_delete(task_id)
title="Delete task"
>
<svg class="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16"/>
</svg>
</button>
</div>
</div>
</div>
}
}
```
### Create Task List Component
Create `client/src/components/tasks/task_list.rs`:
```rust
// client/src/components/tasks/task_list.rs
use leptos::prelude::*;
use shared::{Task, TasksResponse, ApiResponse};
use crate::components::tasks::task_item::TaskItem;
use crate::api::tasks::*;
#[component]
pub fn TaskList() -> impl IntoView {
let (tasks, set_tasks) = signal(Vec::<Task>::new());
let (loading, set_loading) = signal(false);
let (error, set_error) = signal(None::<String>);
let (current_page, set_current_page) = signal(1);
let (total_pages, set_total_pages) = signal(1);
// Load tasks on component mount
Effect::new(move |_| {
spawn_local(async move {
set_loading(true);
set_error(None);
match fetch_tasks(current_page.get_untracked(), 10).await {
Ok(ApiResponse { success: true, data: Some(response), .. }) => {
set_tasks(response.tasks);
set_total_pages((response.total + response.per_page - 1) / response.per_page);
}
Ok(ApiResponse { message: Some(msg), .. }) => {
set_error(Some(msg));
}
Err(e) => {
set_error(Some(format!("Failed to load tasks: {}", e)));
}
}
set_loading(false);
});
});
let handle_toggle = Callback::new(move |task_id: i32| {
spawn_local(async move {
// Find the task and toggle its completion status
let current_tasks = tasks.get_untracked();
if let Some(task) = current_tasks.iter().find(|t| t.id == Some(task_id)) {
let update_request = shared::UpdateTaskRequest {
completed: Some(!task.completed),
title: None,
description: None,
priority: None,
due_date: None,
};
match update_task(task_id, update_request).await {
Ok(ApiResponse { success: true, data: Some(updated_task), .. }) => {
let mut new_tasks = current_tasks;
if let Some(index) = new_tasks.iter().position(|t| t.id == Some(task_id)) {
new_tasks[index] = updated_task;
set_tasks(new_tasks);
}
}
Err(e) => {
set_error(Some(format!("Failed to update task: {}", e)));
}
}
}
});
});
let handle_delete = Callback::new(move |task_id: i32| {
spawn_local(async move {
match delete_task(task_id).await {
Ok(ApiResponse { success: true, .. }) => {
let current_tasks = tasks.get_untracked();
let new_tasks: Vec<Task> = current_tasks
.into_iter()
.filter(|t| t.id != Some(task_id))
.collect();
set_tasks(new_tasks);
}
Err(e) => {
set_error(Some(format!("Failed to delete task: {}", e)));
}
}
});
});
let handle_edit = Callback::new(move |task: Task| {
// For now, just log - you can implement an edit modal here
logging::log!("Edit task: {:?}", task);
});
view! {
<div class="max-w-4xl mx-auto p-6">
<div class="mb-6">
<h1 class="text-3xl font-bold text-gray-900 mb-2">"My Tasks"</h1>
<p class="text-gray-600">"Manage your tasks efficiently"</p>
</div>
{move || {
if loading.get() {
view! {
<div class="text-center py-8">
<div class="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-600 mx-auto"></div>
<p class="mt-4 text-gray-600">"Loading tasks..."</p>
</div>
}
} else if let Some(error_msg) = error.get() {
view! {
<div class="bg-red-50 border border-red-200 rounded-lg p-4">
<div class="flex">
<div class="flex-shrink-0">
<svg class="h-5 w-5 text-red-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.732-.833-2.5 0L3.732 16.5c-.77.833.192 2.5 1.732 2.5z"/>
</svg>
</div>
<div class="ml-3">
<h3 class="text-sm font-medium text-red-800">"Error"</h3>
<div class="mt-2 text-sm text-red-700">
<p>{error_msg}</p>
</div>
</div>
</div>
</div>
}
} else {
let task_list = tasks.get();
if task_list.is_empty() {
view! {
<div class="text-center py-12">
<svg class="mx-auto h-12 w-12 text-gray-400" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 5H7a2 2 0 00-2 2v10a2 2 0 002 2h8a2 2 0 002-2V7a2 2 0 00-2-2

569
book/getting-started/first-run.md
View File

@ -1,569 +0,0 @@
# First Run & Setup
<div align="center">
<img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
</div>
Welcome to your first[Rustelo](/)application! This guide will walk you through setting up and running your application for the first time, ensuring everything is configured correctly and working as expected.
## 🎯 What You'll Accomplish
By the end of this guide, you'll have:
- ✅ **Verified your installation** - Confirmed all tools are working
- ✅ **Started your application** - Both frontend and backend running
- ✅ **Accessed your app** - Connected via web browser
- ✅ **Tested core features** - Authentication, database, and API
- ✅ **Explored the interface** - Understand the user interface
- ✅ **Generated documentation** - Local documentation site running
## 🚀 Quick Start (30 seconds)
If you've already completed the installation, here's the fastest way to get running:
```bash
# Navigate to your project
cd your-rustelo-app
# Start everything
just dev
# Open your browser to:
# http://localhost:3030
```
## 📋 Pre-Run Checklist
Before starting your application, verify these prerequisites:
### 1. Installation Complete
```bash
# Check Rust installation
rustc --version # Should be 1.70.0 or later
cargo --version
# Check Node.js installation
node --version # Should be 18.0.0 or later
npm --version
# Check Rustelo tools
cargo leptos --version
mdbook --version
just --version
```
### 2. Project Structure
```bash
# Verify your project has the correct structure
ls -la
# Should see: client/, server/, shared/, book/, justfile, Cargo.toml, etc.
```
### 3. Environment Configuration
```bash
# Check your .env file exists
cat .env
# Should contain: DATABASE_URL, SESSION_SECRET, etc.
```
### 4. Dependencies Installed
```bash
# Install/update dependencies
cargo build
npm install
```
## 🏃‍♂️ Step-by-Step First Run
### Step 1: Verify Setup
First, let's make sure everything is properly configured:
```bash
# Run the setup verification script
just verify-setup
# This checks:
# - All required tools are installed
# - Environment variables are set
# - Database connection works
# - Dependencies are installed
# - Configuration files are valid
```
**Expected Output:**
```
✅ Rust toolchain: 1.70.0
✅ Node.js: 18.17.0
✅ Database connection: OK
✅ Environment variables: OK
✅ Dependencies: OK
✅ Configuration: Valid
🎉 Your[Rustelo](/)setup is ready!
```
### Step 2: Database Setup
Initialize your database with the required schema:
```bash
# Check database status
just db-status
# Run database migrations
just db-migrate
# Verify database setup
just db-health
```
**Expected Output:**
```
📊 Database Status:
- Type: SQLite
- File: database.db
- Size: 32 KB
- Tables: 3 (users, sessions, tasks)
- Migrations: 3 applied
✅ Database is ready!
```
### Step 3: Start the Application
Now start your[Rustelo](/)application:
```bash
# Start the development server
just dev
# Alternative: Start with verbose logging
just dev-verbose
# Alternative: Start on different port
just dev-port 3031
```
**Expected Output:**
```
🚀 Starting[Rustelo](/)Development Server...
📦 Building frontend assets...
Compiling client v0.1.0
Finished dev [unoptimized + debuginfo] target(s) in 12.3s
🔧 Starting backend server...
Compiling server v0.1.0
Finished dev [unoptimized + debuginfo] target(s) in 8.7s
🌐 Server running on: http://127.0.0.1:3030
🔄 Hot reload enabled on port: 3031
📁 Serving assets from: public/
🗄️ Database: sqlite:database.db
✨ Ready! Your app is running at http://localhost:3030
```
### Step 4: Access Your Application
Open your web browser and navigate to:
**🌐 http://localhost:3030**
You should see:
- **Welcome Page** -[Rustelo](/) landing page
- **Navigation Menu** - Links to different sections
- **Login/Register** - Authentication forms
- **Dashboard** - Main application interface
### Step 5: Test Core Features
Let's test the main features to ensure everything is working:
#### Authentication Test
```bash
# Test authentication endpoints
curl -X POST http://localhost:3030/api/auth/register \
-H "Content-Type: application/json" \
-d '{
"username": "testuser",
"email": "test@example.com",
"password": "testpassword123"
}'
```
**Expected Response:**
```json
{
"success": true,
"data": {
"user_id": 1,
"username": "testuser",
"email": "test@example.com"
},
"message": "User registered successfully"
}
```
#### Database Test
```bash
# Test database connection
just db-health
# View database tables
just db-status
```
#### API Test
```bash
# Test API health endpoint
curl http://localhost:3030/api/health
```
**Expected Response:**
```json
{
"status": "healthy",
"version": "0.1.0",
"uptime": "00:01:23",
"database": "connected"
}
```
## 🎨 Start the Documentation Server
Rustelo includes a comprehensive documentation system:
```bash
# Start documentation server (in a new terminal)
just docs-dev
# This starts mdbook server on http://localhost:3000
```
**Expected Output:**
```
📚 Starting Documentation Server...
2024-01-15 10:30:45 [INFO] (mdbook::book): Book building has started
2024-01-15 10:30:45 [INFO] (mdbook::book): Running the html backend
2024-01-15 10:30:45 [INFO] (mdbook::cmd::serve): Serving on: http://localhost:3000
2024-01-15 10:30:45 [INFO] (mdbook::cmd::serve): Press Ctrl+C to quit.
📖 Documentation available at: http://localhost:3000
```
## 🔧 Common First-Run Issues
### Issue 1: Port Already in Use
**Problem:** `Address already in use (os error 48)`
**Solution:**
```bash
# Check what's using the port
lsof -i :3030
# Kill the process or use a different port
just dev-port 3031
```
### Issue 2: Database Connection Failed
**Problem:** `Failed to connect to database`
**Solution:**
```bash
# Check database file exists
ls -la database.db
# Recreate database
just db-reset
# Run migrations
just db-migrate
```
### Issue 3: Missing Dependencies
**Problem:** `Cannot find binary cargo-leptos`
**Solution:**
```bash
# Install missing tools
cargo install cargo-leptos
cargo install sqlx-cli --features sqlite
# Verify installation
just verify-setup
```
### Issue 4: Environment Variables Missing
**Problem:** `Environment variable not found`
**Solution:**
```bash
# Check .env file exists and is correct
cat .env
# Generate new .env file
cp .env.example .env
# Edit .env with your values
# Load environment variables
source .env
```
### Issue 5: Frontend Build Errors
**Problem:** `npm ERR! or webpack compilation failed`
**Solution:**
```bash
# Clean and reinstall
rm -rf node_modules package-lock.json
npm install
# Rebuild CSS
npm run build:css
# Clear cargo cache
cargo clean
```
## 🎯 Your First Actions
Now that your application is running, here's what you should do:
### 1. Create Your First User Account
1. **Go to:** http://localhost:3030/register
2. **Fill in the form:**
- Username: `your-username`
- Email: `your-email@example.com`
- Password: `your-secure-password`
3. **Click:** "Register"
4. **Verify:** You're redirected to the dashboard
### 2. Explore the Interface
Visit these pages to understand your application:
- **Dashboard:** http://localhost:3030/dashboard - Main application view
- **Profile:** http://localhost:3030/profile - User settings
- **Tasks:** http://localhost:3030/tasks - Task management (if enabled)
- **API Docs:** http://localhost:3030/api/docs - API documentation
### 3. Test Authentication
1. **Logout:** Click the logout button
2. **Login:** Use your credentials to log back in
3. **Verify:** Session persistence works correctly
### 4. Check the Database
```bash
# View your user data
just db-query "SELECT * FROM users;"
# Check sessions
just db-query "SELECT * FROM sessions;"
```
### 5. Explore Documentation
Visit http://localhost:3000 and explore:
- **Getting Started** - This guide and more
- **API Reference** - Complete API documentation
- **Features** - Available features and how to use them
- **Development** - How to customize and extend
## 🛠️ Development Workflow
Now that everything is running, here's your daily development workflow:
### Morning Setup
```bash
# Start your development session
cd your-rustelo-app
just dev # Start app (Terminal 1)
just docs-dev # Start docs (Terminal 2)
just css-watch # Watch CSS changes (Terminal 3)
```
### Making Changes
```bash
# Frontend changes (client/)
# - Edit files in client/src/
# - Changes auto-reload in browser
# Backend changes (server/)
# - Edit files in server/src/
# - Server auto-restarts
# Database changes
just db-migration create_new_feature
# - Edit migration file
just db-migrate
```
### Testing Changes
```bash
# Run tests
just test
# Check code quality
just check
# Build for production
just build-prod
```
## 📊 Performance Monitoring
Monitor your application's performance:
### Real-time Metrics
```bash
# View system metrics
just health
# Check memory usage
just monitor-resources
# View logs
just logs
```
### Browser DevTools
1. **Open DevTools** (F12)
2. **Network Tab** - Monitor API calls
3. **Console Tab** - Check for errors
4. **Performance Tab** - Analyze load times
## 🔍 Debugging Tips
### Enable Debug Logging
```bash
# Set debug level in .env
LOG_LEVEL=debug
# Restart server
just dev
```
### Common Debug Commands
```bash
# View detailed logs
just logs-verbose
# Check server health
curl http://localhost:3030/api/health
# Test database queries
just db-query "SELECT COUNT(*) FROM users;"
# Verify configuration
just config-status
```
## 🎉 Success Checklist
Verify your first run was successful:
- [ ] **Application starts without errors**
- [ ] **Web interface loads at http://localhost:3030**
- [ ] **User registration works**
- [ ] **User login works**
- [ ] **Database operations work**
- [ ] **API endpoints respond correctly**
- [ ] **Documentation site loads at http://localhost:3000**
- [ ] **Hot reload works for frontend changes**
- [ ] **Backend restarts on changes**
- [ ] **No errors in console logs**
## 🚀 Next Steps
Congratulations! Your Rustelo application is now running. Here's what to do next:
### Immediate Next Steps (Today)
1. **[Build Your First App](./first-app.md)** - Create a complete application
2. **[Configure Features](./configuration.md)** - Enable additional features
3. **[Explore Components](../developers/components/README.md)** - Learn about available components
### Short-term Goals (This Week)
1. **Customize Styling** - Update colors, fonts, and layout
2. **Add Content** - Create pages and content for your app
3. **Configure Production** - Set up production deployment
4. **Add Features** - Enable email, content management, etc.
### Long-term Goals (This Month)
1. **Deploy to Production** - Launch your app
2. **Set up Monitoring** - Track performance and errors
3. **Add Custom Features** - Build app-specific functionality
4. **Scale Your App** - Optimize for growth
## 🆘 Getting Help
If you encounter issues:
### Quick Fixes
```bash
# Reset everything
just clean-all
just setup
# Verify setup
just verify-setup
# Check logs
just logs
```
### Documentation Resources
- **[Troubleshooting Guide](../troubleshooting/common.md)** - Common issues and solutions
- **[Configuration Guide](../configuration/README.md)** - Advanced configuration options
### Community Support
- **GitHub Issues** - Report bugs and request features
- **Discord Server** - Real-time help and discussion
- **Stack Overflow** - Tag questions with `rustelo`
## 💡 Pro Tips
### Development Efficiency
- **Use `just help`** - See all available commands
- **Keep docs running** - Reference documentation while coding
- **Use hot reload** - Changes appear instantly
- **Check logs regularly** - Catch issues early
### Best Practices
- **Commit often** - Small, frequent commits
- **Test thoroughly** - Use `just test` before commits
- **Monitor performance** - Use `just health` regularly
- **Document changes** - Update documentation as you build
### Security
- **Change default secrets** - Use secure SESSION_SECRET and JWT_SECRET
- **Use HTTPS in production** - Enable TLS feature
- **Keep dependencies updated** - Regular `just update`
- **Monitor security** - Use `just security-audit`
## 🎊 You're Ready!
Your[Rustelo](/) application is now running successfully! You have:
- ✅ **A working web application** with authentication
- ✅ **A development environment** with hot reload
- ✅ **A documentation system** for reference
- ✅ **Database connectivity** for data persistence
- ✅ **API endpoints** for frontend-backend communication
- ✅ **All tools configured** for productive development
**Time to start building something amazing!** 🚀
---
**Next:** Continue with [Building Your First App](./first-app.md) to create a complete application, or explore [Configuration](./configuration.md) to customize your setup.
Happy coding! 🦀✨

544
book/getting-started/installation.md
View File

@ -1,544 +0,0 @@
# Quick Installation
<div align="center">
<img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
</div>
This guide will help you install[Rustelo](/) and set up your development environment quickly and efficiently.
## Prerequisites
Before installing Rustelo, ensure you have the following prerequisites:
### System Requirements
- **Operating System**: Linux, macOS, or Windows (WSL2 recommended for Windows)
- **Memory**: Minimum 4GB RAM, 8GB+ recommended for comfortable development
- **Storage**: At least 2GB free space for tools and dependencies
- **Internet Connection**: Required for downloading dependencies
### Required Tools
#### 1. Rust Programming Language
Rustelo requires Rust 1.70.0 or later.
**Install Rust using rustup:**
```bash
# Install rustup (Rust installer and version manager)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Follow the on-screen instructions, then restart your shell or run:
source ~/.cargo/env
# Verify installation
rustc --version # Should be 1.70.0 or later
cargo --version
```
**Update existing Rust installation:**
```bash
rustup update
```
#### 2. Node.js and npm (for frontend assets)
Node.js 18.0.0 or later is required for building frontend assets.
**Option 1: Using Node Version Manager (recommended)**
```bash
# Install nvm (Linux/macOS)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Restart your shell or run:
source ~/.bashrc
# Install and use Node.js 18
nvm install 18
nvm use 18
# Option 2: Direct installation
# Visit https://nodejs.org/ and download LTS version
# Verify installation
node --version # Should be 18.0.0 or later
npm --version
```
#### 3. Git
Git is required for version control and dependency management.
**Linux (Ubuntu/Debian):**
```bash
sudo apt update
sudo apt install git
```
**Linux (RHEL/CentOS/Fedora):**
```bash
sudo dnf install git
# or for older versions: sudo yum install git
```
**macOS:**
```bash
# Using Homebrew
brew install git
# Or download from https://git-scm.com/download/mac
```
**Windows:**
```bash
# Download from https://git-scm.com/download/win
# Verify installation
git --version
```
### Recommended Tools
#### 1. cargo-leptos
Essential for building Leptos applications:
```bash
cargo install cargo-leptos
# Verify installation
cargo leptos --version
```
#### 2. SQLx CLI
For database migrations and management:
```bash
cargo install sqlx-cli --features postgres,sqlite
# Verify installation
sqlx --version
```
#### 3. Just (command runner)
Optional but recommended for task automation:
```bash
cargo install just
# Verify installation
just --version
```
#### 4. mdBook (for documentation)
If you plan to work with documentation:
```bash
cargo install mdbook
# Verify installation
mdbook --version
```
## Installation Methods
### Method 1: Clone from Repository (Recommended for Development)
This method gives you the complete[Rustelo](/) template with all features:
```bash
# Clone the repository
git clone https://github.com/yourusername/rustelo.git
cd rustelo
# Copy the template to your project
cp -r template my-rustelo-app
cd my-rustelo-app
# Install dependencies
cargo build
# Install npm dependencies for frontend
npm install
```
### Method 2: Use as Template
Create a new repository using Rustelo as a template:
1. Go to the[Rustelo](/) repository on GitHub
2. Click "Use this template"
3. Create your new repository
4. Clone your new repository:
```bash
git clone https://github.com/yourusername/your-new-app.git
cd your-new-app
# Install dependencies
cargo build
npm install
```
### Method 3: Download and Extract
Download the latest release:
```bash
# Download the latest release
curl -L https://github.com/yourusername/rustelo/archive/main.zip -o rustelo.zip
# Extract
unzip rustelo.zip
cd rustelo-main/template
# Install dependencies
cargo build
npm install
```
## Database Setup
Rustelo supports both SQLite and PostgreSQL. Choose based on your needs:
### Option 1: SQLite (Recommended for Development)
SQLite requires no additional setup and is perfect for development:
```bash
# Set database URL (optional, SQLite is the default)
export DATABASE_URL="sqlite//:database.db"
```
### Option 2: PostgreSQL (Recommended for Production)
#### Option 2a: Using Docker (Easiest)
```bash
# Start PostgreSQL container
docker run -d \
--name rustelo-postgres \
-e POSTGRES_PASSWORD=password \
-e POSTGRES_DB=rustelo \
-p 5432:5432 \
postgres:15
# Set database URL
export DATABASE_URL="postgresql://postgres:password@localhost:5432/rustelo"
```
#### Option 2b: Native Installation
**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql
# Create database
sudo -u postgres createdb rustelo
sudo -u postgres psql -c "CREATE USER rustelo WITH PASSWORD 'password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE rustelo TO rustelo;"
```
**macOS:**
```bash
# Using Homebrew
brew install postgresql
brew services start postgresql
# Create database
createdb rustelo
psql rustelo -c "CREATE USER rustelo WITH PASSWORD 'password';"
psql rustelo -c "GRANT ALL PRIVILEGES ON DATABASE rustelo TO rustelo;"
```
**Windows:**
```bash
# Download and install from https://www.postgresql.org/download/windows/
# Follow the installation wizard
# Use pgAdmin or command line to create database
```
## Environment Configuration
### 1. Create Environment File
Create a `.env` file in your project root:
```bash
cat > .env << EOF
# Database configuration
DATABASE_URL=sqlite//:database.db
# Security secrets (change these!)
SESSION_SECRET=your-session-secret-here
JWT_SECRET=your-jwt-secret-here
# Application settings
RUSTELO_ENV=development
RUSTELO_LOG_LEVEL=debug
# Optional: Email configuration (if using email features)
# SMTP_HOST=smtp.gmail.com
# SMTP_USERNAME=your-email@gmail.com
# SMTP_PASSWORD=your-app-password
# FROM_EMAIL=noreply@yourapp.com
EOF
```
### 2. Generate Secure Secrets
For production or if you want secure development secrets:
```bash
# Generate session secret
openssl rand -base64 32
# Generate JWT secret
openssl rand -base64 32
# Update your .env file with these values
```
### 3. Build Configuration
Generate your application configuration:
```bash
# Build development configuration
./config/scripts/build-config.sh dev
# This creates config.toml with all your settings
```
## Verify Installation
### 1. Check Dependencies
```bash
# Check Rust
rustc --version
cargo --version
# Check Node.js
node --version
npm --version
# Check Git
git --version
# Check optional tools
cargo leptos --version
sqlx --version
just --version
```
### 2. Build Project
```bash
# Build the project
cargo build
# Build frontend assets
npm run build
# Or use leptos build command
cargo leptos build
```
### 3. Run Tests
```bash
# Run Rust tests
cargo test
# Run with all features
cargo test --all-features
```
### 4. Start Development Server
```bash
# Load environment variables
source .env
# Start development server
cargo leptos watch
# Or use just if available
just dev
```
Your application should now be running at `http://localhost:3030`!
## Post-Installation Setup
### 1. Database Migrations
If using a SQL database, run initial migrations:
```bash
# Create initial migration (if not exists)
sqlx migrate add initial
# Run migrations
sqlx migrate run
```
### 2. Create Admin User (Optional)
Some applications may need an initial admin user:
```bash
# This depends on your application setup
cargo run --bin create-admin-user
```
### 3. Configure Features
Enable the features you need by editing your configuration:
```bash
# Edit configuration
./config/scripts/build-config.sh dev
# Enable specific features in config/features/
```
## Development Environment Setup
### 1. IDE Configuration
**VS Code (Recommended):**
Install recommended extensions:
- rust-analyzer
- Leptos Language Server
- TOML Language Support
- SQLx Language Server
**Other IDEs:**
- IntelliJ IDEA with Rust plugin
- Neovim with rust-analyzer
- Emacs with rust-mode
### 2. Git Configuration
Set up Git hooks and configuration:
```bash
# Configure git (if not already done)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"
# Set up pre-commit hooks (optional)
cargo install pre-commit
pre-commit install
```
### 3. Development Tools
Install additional development tools:
```bash
# Code formatting
rustup component add rustfmt
# Linting
rustup component add clippy
# Documentation
cargo install cargo-doc
# Watch for changes
cargo install cargo-watch
```
## Troubleshooting
### Common Installation Issues
#### Rust Installation Problems
```bash
# If rustup installation fails
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --no-modify-path
# Add to PATH manually
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```
#### cargo-leptos Installation Issues
```bash
# If cargo-leptos fails to install
cargo install cargo-leptos --force
# Or install specific version
cargo install cargo-leptos --version 0.2.1
```
#### Database Connection Issues
```bash
# Test SQLite
sqlite3 database.db ".tables"
# Test PostgreSQL
psql $DATABASE_URL -c "SELECT version();"
```
#### Permission Issues (Linux/macOS)
```bash
# If you get permission errors
sudo chown -R $USER:$USER ~/.cargo
chmod -R u+rw ~/.cargo
```
### Performance Issues
If compilation is slow:
```bash
# Use faster linker (Linux)
sudo apt install lld
export RUSTFLAGS="-C link-arg=-fuse-ld=lld"
# Use faster linker (macOS)
export RUSTFLAGS="-C link-arg=-fuse-ld=/usr/bin/ld"
# Increase parallel compilation
export CARGO_BUILD_JOBS=4
```
### Getting Help
If you encounter issues:
1. **Check system requirements** - Ensure you meet all prerequisites
2. **Update tools** - Make sure Rust and other tools are up to date
3. **Check logs** - Look at error messages carefully
4. **Search documentation** - Check the troubleshooting guide
5. **Community support** - Ask questions in forums or chat
6. **GitHub issues** - Report bugs on the repository
## Next Steps
After successful installation:
1. **[Basic Configuration](./configuration.md)** - Configure your application settings
2. **[First Run & Setup](./first-run.md)** - Get your application running
3. **[Development Workflow](../developers/setup/workflow.md)** - Learn the development process
4. **[Project Structure](../developers/setup/structure.md)** - Understand the codebase organization
Congratulations! You now have[Rustelo](/) installed and ready for development. 🎉

374
book/getting-started/quick-start.md
View File

@ -1,374 +0,0 @@
# Quick Start
<div align="center">
<img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
</div>
Get up and running with[Rustelo](/) in just a few minutes! This guide will help you create your first[Rustelo](/) application with minimal setup.
## Prerequisites
Before you begin, ensure you have the following installed:
- **Rust** (1.75 or later) - [Install Rust](https://rustup.rs/)
- **Node.js** (18 or later) - [Install Node.js](https://nodejs.org/)
- **Git** - [Install Git](https://git-scm.com/)
Optional but recommended:
- **Docker** - For database setup and deployment
- **cargo-leptos** - For enhanced development experience
## 30-Second Setup
### 1. Clone the Template
```bash
git clone https://github.com/yourusername/rustelo.git my-app
cd my-app
```
### 2. Run the Interactive Setup
```bash
./scripts/configure-features.sh
```
This interactive script will:
- Help you choose which features to enable
- Set up your environment configuration
- Install necessary dependencies
- Initialize your database (if needed)
### 3. Start Development Server
```bash
cargo run
```
Your application will be available at `http://localhost:3030`
## Manual Setup
If you prefer to configure everything manually:
### 1. Choose Your Features
Rustelo uses a modular feature system. Choose the combination that fits your needs:
```bash
# Minimal static website
cargo build --no-default-features
# Static website with HTTPS
cargo build --no-default-features --features "tls"
# Authentication-enabled app
cargo build --no-default-features --features "auth"
# Full-featured application (default)
cargo build --features "auth,content-db,email"
```
### 2. Configure Environment
Create a `.env` file in your project root:
```bash
# Basic configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=3030
SERVER_PROTOCOL=http
ENVIRONMENT=DEV
LOG_LEVEL=info
# Database (if using auth or content-db features)
DATABASE_URL=sqlite//:database.db
# JWT (if using auth feature)
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_EXPIRATION_HOURS=24
```
### 3. Start the Application
```bash
cargo run
```
## First Steps
Once your application is running, you can:
### Access Your Application
- **Frontend**: `http://localhost:3030`
- **Health Check**: `http://localhost:3030/api/health`
### Explore the Structure
```
my-app/
├── client/ # Frontend Leptos components
├── server/ # Backend Axum server
├── shared/ # Shared types and utilities
├── content/ # Static content files
├── docs/ # Documentation
├── migrations/ # Database migrations
└── scripts/ # Helper scripts
```
### Try Different Configurations
#### Static Website
```bash
# Stop the current server (Ctrl+C)
cargo run --no-default-features
```
Perfect for: Marketing sites, documentation, landing pages
#### Authentication-Enabled
```bash
# Requires database setup
cargo run --features "auth"
```
Perfect for: User portals, SaaS applications
#### Content Management
```bash
# Requires database setup
cargo run --features "content-db"
```
Perfect for: Blogs, news sites, CMS
## Common First Tasks
### 1. Customize the Homepage
Edit `client/src/pages/home.rs`:
```rust
#[component]
pub fn HomePage() -> impl IntoView {
view! {
<div class="hero min-h-screen bg-base-200">
<div class="hero-content text-center">
<div class="max-w-md">
<h1 class="text-5xl font-bold">"Welcome to My App"</h1>
<p class="py-6">"Your awesome application built with Rustelo"</p>
</div>
</div>
</div>
}
}
```
### 2. Add a New Page
Create `client/src/pages/about.rs`:
```rust
use leptos::*;
#[component]
pub fn AboutPage() -> impl IntoView {
view! {
<div class="container mx-auto px-4 py-8">
<h1 class="text-3xl font-bold mb-4">"About Us"</h1>
<p>"This is our awesome application!"</p>
</div>
}
}
```
Add it to the router in `client/src/app.rs`:
```rust
<Route path="/about" view=AboutPage/>
```
### 3. Add Authentication (Optional)
If you enabled the `auth` feature, you can add login/register forms:
```rust
use leptos::*;
use shared::auth::*;
#[component]
pub fn LoginPage() -> impl IntoView {
let (email, set_email) = create_signal(String::new());
let (password, set_password) = create_signal(String::new());
let login_action = create_action(|credentials: &LoginRequest| {
let credentials = credentials.clone();
async move {
// Login logic here
}
});
view! {
<div class="card w-96 bg-base-100 shadow-xl">
<div class="card-body">
<h2 class="card-title">"Login"</h2>
<div class="form-control">
<label class="label">
<span class="label-text">"Email"</span>
</label>
<input
type="email"
class="input input-bordered"
on:input=move |ev| set_email.set(event_target_value(&ev))
/>
</div>
<div class="form-control">
<label class="label">
<span class="label-text">"Password"</span>
</label>
<input
type="password"
class="input input-bordered"
on:input=move |ev| set_password.set(event_target_value(&ev))
/>
</div>
<div class="card-actions justify-end">
<button
class="btn btn-primary"
on:click=move |_| {
login_action.dispatch(LoginRequest {
email: email.get(),
password: password.get(),
});
}
>
"Login"
</button>
</div>
</div>
</div>
}
}
```
## Database Setup (Optional)
If you're using features that require a database (`auth` or `content-db`):
### SQLite (Recommended for development)
```bash
# Already configured with DATABASE_URL=sqlite:database.db
# The database file will be created automatically
```
### PostgreSQL (Recommended for production)
```bash
# Start PostgreSQL with Docker
docker run -d \
--name postgres \
-e POSTGRES_PASSWORD=password \
-e POSTGRES_DB=rustelo \
-p 5432:5432 \
postgres:15
# Update your .env file
DATABASE_URL=postgresql://postgres:password@localhost:5432/rustelo
```
### Run Migrations
```bash
# Install sqlx-cli if not already installed
cargo install sqlx-cli
# Run migrations
sqlx migrate run
```
## Development Tips
### Hot Reloading
For the best development experience, use `cargo-leptos`:
```bash
# Install cargo-leptos
cargo install cargo-leptos
# Start with hot reloading
cargo leptos serve
```
### Database Inspection
```bash
# SQLite
sqlite3 database.db ".tables"
# PostgreSQL
psql postgresql://postgres:password@localhost:5432/rustelo -c "\dt"
```
### Logs and Debugging
```bash
# Verbose logging
LOG_LEVEL=debug cargo run
# Trace level (very verbose)
LOG_LEVEL=trace cargo run
```
## Next Steps
Now that you have[Rustelo](/) running, here are some suggested next steps:
1. **[Learn about Features](../features/overview.md)** - Understand what each feature provides
2. **[Project Structure](../development/structure.md)** - Get familiar with the codebase
3. **[Configuration](../configuration/environment.md)** - Configure your application
4. **[Database Setup](../database/overview.md)** - Set up your database properly
5. **[Deployment](../deployment/overview.md)** - Deploy your application
## Troubleshooting
### Common Issues
**Port already in use:**
```bash
# Change the port in .env
SERVER_PORT=3031
```
**Database connection error:**
```bash
# Check if PostgreSQL is running
docker ps
# Or use SQLite instead
DATABASE_URL=sqlite//:database.db
```
**Build errors:**
```bash
# Clean build
cargo clean && cargo build
# Update dependencies
cargo update
```
**Permission denied on scripts:**
```bash
chmod +x scripts/configure-features.sh
```
### Getting Help
- **Documentation**: Check the relevant sections in this book
- **Examples**: Look at the `examples/` directory
- **Issues**: Search or create an issue on GitHub
- **Community**: Join our discussions
## What's Next?
Congratulations! You now have a working[Rustelo](/) application. Here are some recommended next steps:
- **Customize the UI**: Modify the frontend components to match your design
- **Add Business Logic**: Implement your application's core functionality
- **Set Up Database**: Configure your preferred database system
- **Add Authentication**: Enable user management if needed
- **Deploy**: Get your application ready for production
Ready to dive deeper? Continue with the [Installation](./installation.md) guide for more detailed setup instructions.

299
book/getting-started/what-is-rustelo.md
View File

@ -1,299 +0,0 @@
# What is Rustelo?
<div align="center">
<img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
</div>
Rustelo is a modern, high-performance web application framework built with Rust that combines the best of both worlds: the safety and speed of systems programming with the flexibility and ease of web development.
## The Rustelo Philosophy
### Built for the Modern Web
Rustelo was designed from the ground up to address the challenges of modern web development:
- **Performance First** - Every component is optimized for speed and efficiency
- **Security by Default** - Built-in protections against common web vulnerabilities
- **Developer Experience** - Tools and patterns that make development enjoyable
- **Production Ready** - Tested and proven in real-world applications
### Why Rust for Web Development?
Traditional web frameworks often force you to choose between performance and safety.[Rustelo](/) breaks this false dichotomy by leveraging Rust's unique advantages:
#### Memory Safety Without Garbage Collection
```rust
// No null pointer exceptions
// No buffer overflows
// No memory leaks
// No data races
```
#### Zero-Cost Abstractions
```rust
// High-level code that compiles to fast machine code
async fn handle_request(req: Request) -> Response {
let user = authenticate(&req).await?;
let content = fetch_content(&user).await?;
render_response(content)
}
```
#### Fearless Concurrency
```rust
// Handle thousands of concurrent users safely
#[tokio::main]
async fn main() {
let app = create_app().await;
let listener = tokio::net::TcpListener::bind("0.0.0.0:3030").await?;
axum::serve(listener, app).await?;
}
```
## Core Architecture
### Frontend: Reactive and Fast
Rustelo uses **Leptos** for the frontend, providing:
- **Server-Side Rendering (SSR)** - Fast initial page loads
- **Client-Side Hydration** - Interactive user experience
- **Reactive Components** - Efficient updates and state management
- **WebAssembly** - Near-native performance in the browser
### Backend: Robust and Scalable
The backend is powered by **Axum**, offering:
- **Async-First Design** - Handle many concurrent requests
- **Type-Safe Routing** - Catch errors at compile time
- **Middleware System** - Composable request/response processing
- **Tower Integration** - Rich ecosystem of networking components
### Database: Flexible and Reliable
Database integration through **SQLx** provides:
- **Compile-Time SQL Checking** - Catch database errors before deployment
- **Multiple Database Support** - PostgreSQL, SQLite, and more
- **Connection Pooling** - Efficient resource management
- **Migration System** - Version-controlled schema changes
## Feature Ecosystem
### Modular by Design
Rustelo uses Rust's feature flags to create a modular system:
```toml
[features]
default = ["auth", "content-db", "email"]
# Core features
auth = ["jsonwebtoken", "argon2", "oauth2"]
content-db = ["pulldown-cmark", "syntect", "sqlx"]
email = ["lettre", "handlebars"]
tls = ["rustls", "axum-server/tls"]
```
This means you only compile and include what you actually use.
### Available Modules
#### 🔐 Authentication Module
- JWT token-based authentication
- OAuth2 integration (Google, GitHub, etc.)
- Two-factor authentication (TOTP)
- Session management
- Role-based access control (RBAC)
#### 📝 Content Management Module
- Markdown rendering with syntax highlighting
- Rich text editing interface
- Media file management
- Content versioning
- SEO optimization tools
#### 📧 Email Module
- Multiple email providers (SMTP, SendGrid, AWS SES)
- HTML and text templates
- Contact forms
- Email verification workflows
- Newsletter capabilities
#### 🔒 Security Module
- HTTPS/TLS encryption
- CSRF protection
- Rate limiting
- Security headers
- Input validation and sanitization
## Real-World Benefits
### For End Users
- **Fast Loading** - Pages load quickly and stay responsive
- **Secure** - Your data is protected by industry best practices
- **Reliable** - Applications stay up and running
- **Mobile-Friendly** - Works perfectly on all devices
### For Developers
- **Productive** - Rich tooling and clear error messages
- **Maintainable** - Type safety prevents many bugs
- **Scalable** - Performance that grows with your users
- **Enjoyable** - Modern development experience
### For Businesses
- **Cost-Effective** - Lower server costs due to efficiency
- **Secure** - Reduced risk of data breaches
- **Fast Time-to-Market** - Rapid development cycles
- **Future-Proof** - Built on growing, stable technology
## Comparison with Other Frameworks
### vs. Node.js Frameworks
| Aspect | Rustelo | Node.js |
|--------|---------|---------|
| Performance | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| Memory Safety | ⭐⭐⭐⭐⭐ | ⭐⭐ |
| Type Safety | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| Ecosystem | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Learning Curve | ⭐⭐⭐ | ⭐⭐⭐⭐ |
### vs. Python Frameworks
| Aspect | Rustelo | Django/Flask |
|--------|---------|-------------|
| Performance | ⭐⭐⭐⭐⭐ | ⭐⭐ |
| Concurrency | ⭐⭐⭐⭐⭐ | ⭐⭐ |
| Type Safety | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| Development Speed | ⭐⭐⭐ | ⭐⭐⭐⭐ |
| Runtime Errors | ⭐⭐⭐⭐⭐ | ⭐⭐ |
### vs. Go Frameworks
| Aspect | Rustelo | Go |
|--------|---------|-----|
| Performance | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| Memory Safety | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
| Frontend Integration | ⭐⭐⭐⭐⭐ | ⭐⭐ |
| Compile Time | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| Error Handling | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
## When to Choose Rustelo
### Perfect For:
- **High-Performance Applications** - When speed matters
- **Security-Critical Systems** - When safety is paramount
- **Long-Term Projects** - When maintainability is key
- **Growing Applications** - When you need to scale
- **Modern Development Teams** - When you want the latest tools
### Consider Alternatives If:
- **Rapid Prototyping** - When you need something in hours, not days
- **Large Existing Ecosystem** - When you need tons of third-party packages
- **Team Constraints** - When your team isn't ready for Rust
- **Simple CRUD Apps** - When basic functionality is sufficient
## Success Stories
### Performance Gains
> "We migrated our API from Node.js to[Rustelo](/) and saw a 10x improvement in response times while reducing server costs by 60%."
>
> — *Tech Lead at Growing SaaS Company*
### Developer Experience
> "The type safety caught so many bugs before they reached production. Our deployment confidence went through the roof."
>
> — *Senior Developer at Fintech Startup*
### Scalability
> "Rustelo handled our traffic spike during a viral campaign without any issues. The old system would have crashed."
>
> — *CTO at Media Company*
## The Technology Stack
### Frontend Technologies
- **Leptos** - Reactive web framework
- **WebAssembly** - High-performance client code
- **Tailwind CSS** - Utility-first styling
- **DaisyUI** - Beautiful components
### Backend Technologies
- **Axum** - Fast, ergonomic web server
- **Tokio** - Async runtime
- **Tower** - Modular networking
- **SQLx** - Type-safe database queries
### Infrastructure
- **Docker** - Containerized deployment
- **PostgreSQL/SQLite** - Flexible database options
- **Nginx** - Reverse proxy and load balancing
- **Let's Encrypt** - Automatic SSL certificates
## Getting Started Journey
### For Different User Types
#### Content Creators & Bloggers
1. **[Installation](./installation.md)** - Get Rustelo running
2. **[User Interface](../users/interface.md)** - Learn the admin panel
3. **[Content Publishing](../users/content.md)** - Create your first post
4. **[Customization](../users/profile.md)** - Make it yours
#### Developers & Teams
1. **[Development Setup](../developers/setup/environment.md)** - Configure your tools
2. **[Architecture Overview](../developers/architecture/overview.md)** - Understand the system
3. **[First Feature](../developers/features/adding-features.md)** - Build something
4. **[Testing](../developers/testing/strategy.md)** - Ensure quality
#### System Administrators
1. **[Production Installation](../deployment/production.md)** - Deploy securely
2. **[Configuration](../configuration/environment.md)** - Optimize settings
3. **[Monitoring](../deployment/monitoring.md)** - Keep it healthy
4. **[Backup Strategy](../deployment/backup.md)** - Protect your data
## Community and Ecosystem
### Open Source Benefits
- **Transparency** - You can see exactly how everything works
- **Security** - Many eyes make bugs shallow
- **Flexibility** - Modify anything to fit your needs
- **Longevity** - Not dependent on any single company
### Growing Ecosystem
- **Active Development** - Regular updates and improvements
- **Community Plugins** - Extensions built by users
- **Documentation** - Comprehensive guides and examples
- **Support** - Multiple channels for getting help
### Contributing Opportunities
- **Code Contributions** - Features, bug fixes, optimizations
- **Documentation** - Guides, tutorials, translations
- **Testing** - Quality assurance and feedback
- **Community** - Help other users succeed
## The Future of Rustelo
### Roadmap Highlights
- **Performance Optimizations** - Even faster response times
- **Enhanced Developer Tools** - Better debugging and profiling
- **More Integrations** - Additional third-party services
- **Mobile-First Features** - Progressive Web App capabilities
- **AI/ML Integration** - Modern AI-powered features
### Long-Term Vision
Rustelo aims to be the go-to framework for building high-performance, secure web applications that can grow from prototype to enterprise scale while maintaining developer productivity and system reliability.
## Next Steps
Ready to experience Rustelo? Here's what to do next:
### Try It Out
- **[Quick Installation](./installation.md)** - Get running in minutes
- **[Live Demo](https://demo.rustelo.dev)** - See it in action
- **[Example Applications](https://github.com/rustelo/examples)** - Real-world code
### Learn More
- **[Architecture Deep Dive](../developers/architecture/overview.md)** - Technical details
- **[Feature Comparison](../reference/features.md)** - What's included
- **[Performance Benchmarks](../performance/overview.md)** - How fast is it?
### Get Involved
- **[Community Forum](https://forum.rustelo.dev)** - Join the discussion
- **[GitHub Repository](https://github.com/rustelo/rustelo)** - See the code
- **[Contributing Guide](../contributing/guidelines.md)** - Help improve Rustelo
---
*Rustelo represents the future of web development: safe, fast, and enjoyable. Join us in building better web applications with the power of Rust.* 🦀⚡

0
book/glossary.md
View File

Some files were not shown because too many files have changed in this diff Show More