Rustelo/book/features/detailed.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:

# Environment variables
SERVER_PROTOCOL=https
TLS_CERT_PATH=/path/to/certificate.pem
TLS_KEY_PATH=/path/to/private_key.pem

Usage:

# 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:

# 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:

# 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)

cargo build --no-default-features

This provides a basic Leptos application with static content only.

Basic Setup (No database)

cargo build --no-default-features --features tls

Basic application with TLS support but no database features.

Authentication Only

cargo build --no-default-features --features auth

Includes authentication system but no database content management.

Content Management Only

cargo build --no-default-features --features content-db

Includes database-driven content but no authentication.

Full Featured (Default)

cargo build --features "auth,content-db"
# or simply
cargo build

All features enabled for a complete application.

Production Setup

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:

# 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:

# Build with specific features
ARG FEATURES="tls,auth,content-db"
RUN cargo build --release --features ${FEATURES}

Development vs Production

Development

# Development with all features
cargo run

# Development without TLS
cargo run --no-default-features --features "auth,content-db"

Production

# 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