Rustelo/info/features.md

# Rustelo Features Configuration

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