Rustelo/QUICK_START.md

Rustelo Quick Start Guide

Get up and running with Rustelo in just a few minutes! This comprehensive guide will take you from zero to a fully functional web application with documentation.

🚀 30-Second Setup

Prerequisites Check

Before starting, ensure you have:

• Git - Version control
• Internet connection - For downloading dependencies

One-Command Installation

# Clone and install everything automatically
git clone https://github.com/yourusername/rustelo.git my-app
cd my-app
./scripts/install.sh

That's it! The installer will:

• ✅ Install Rust, Node.js, and all required tools
• ✅ Install mdBook and Just task runner
• ✅ Set up your project with sensible defaults
• ✅ Configure documentation system
• ✅ Verify everything is working
• ✅ Generate a personalized setup report

🎯 What You Get

After installation, you'll have:

📁 Complete Project Structure

my-app/
├── client/          # Frontend Leptos components
├── server/          # Backend Axum server
├── shared/          # Shared code and types
├── book/            # Documentation source (mdBook)
├── scripts/         # Helper scripts
├── .env            # Environment configuration
├── justfile        # Task runner commands
└── book.toml       # Documentation configuration

🛠️ Essential Tools Ready

• Rust with Cargo - Main development tools
• mdBook - Documentation system
• Just - Task runner for easy commands
• cargo-leptos - Leptos development server

📚 Documentation System

• Interactive documentation website
• Auto-synced content from your docs
• Multiple deployment options
• Mobile-friendly design

📋 Setup Report

• SETUP_COMPLETE.md - Personalized installation summary
• Shows exactly what was installed and configured
• Includes quick start commands for your specific setup
• Updates automatically after any setup changes

🏃‍♂️ Start Developing

1. Start Development Servers

# Start the web application
just dev

# In another terminal, start documentation server
just docs-dev

2. Open Your App

• Web App: http://localhost:3030
• Documentation: http://localhost:3000

3. Make Your First Change

Edit client/src/pages/home.rs:

#[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">"Hello, Rustelo!"</h1>
                    <p class="py-6">"Your web app is ready to build amazing things!"</p>
                </div>
            </div>
        </div>
    }
}

🎛️ Essential Commands

Development

# Start development server with hot reload
just dev

# Start documentation server
just docs-dev

# Run tests
just test

# Check code quality
just check

# Build for production
just build-prod

Documentation

# Setup documentation system
just docs-setup

# Build documentation
just docs-build

# Deploy to GitHub Pages
just docs-deploy-github

# Clean documentation build
just docs-clean

# Show all documentation commands
just help-docs

System

# Verify installation
just verify-setup

# Show all available commands
just help

# Generate setup completion report
just generate-setup-report

# Update dependencies
just update

🔧 Configuration Options

Choose Your Features

Rustelo is modular. Choose what you need:

# Minimal static website
cargo build --no-default-features

# Full-featured app (default)
cargo build --features "auth,content-db,email"

# Production with HTTPS
cargo build --features "tls,auth,content-db,email"

Environment Configuration

Edit .env to customize your setup:

# Basic Configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=3030
ENVIRONMENT=dev

# Features (true/false)
ENABLE_AUTH=true
ENABLE_CONTENT_DB=true
ENABLE_TLS=false

# Database (choose one)
DATABASE_URL=sqlite:database.db                    # SQLite (simple)
# DATABASE_URL=postgresql://user:pass@localhost:5432/db  # PostgreSQL (production)

# Logging
LOG_LEVEL=debug

📖 Documentation Features

What's Included

• 📚 Interactive Guide - Searchable, mobile-friendly documentation
• 🔄 Auto-Sync - Automatically includes your existing docs
• 🌐 Multi-Deploy - GitHub Pages, Netlify, Vercel, Docker
• 🎨 Custom Styling - Branded documentation with your colors
• 📱 Mobile-First - Works perfectly on all devices

Customize Documentation

# Edit content in book/ directory
# Add your own sections in book/SUMMARY.md
# Customize styling in book/theme/custom.css

# Build and preview
just docs-build
just docs-dev

🗄️ Database Setup

SQLite (Development)

# Already configured! Database file created automatically
# Perfect for: Development, testing, small apps

PostgreSQL (Production)

# Start PostgreSQL with Docker
docker run -d -p 5432:5432 \
  -e POSTGRES_PASSWORD=password \
  -e POSTGRES_DB=myapp \
  postgres:15

# Update .env
DATABASE_URL=postgresql://postgres:password@localhost:5432/myapp

# Run migrations
just db-migrate

🚀 Deployment

Quick Deploy to GitHub Pages

# Deploy documentation
just docs-deploy-github

# Deploy will be available at:
# https://yourusername.github.io/my-app

Check Your Setup

# View detailed setup information
cat SETUP_COMPLETE.md

# Regenerate setup report
just regenerate-setup-report

# Verify everything is working
just verify-setup

Production Deployment

# Build for production
just build-prod

# Deploy with Docker
just docker-build
just docker-run

# Or deploy to cloud platform of choice

🛠️ Development Workflow

Daily Development

# Morning routine
just verify-setup    # Verify everything is working
just dev              # Start development server
just docs-dev         # Start documentation (separate terminal)

# Make changes, they auto-reload!

# Evening routine
just test             # Run tests
just docs-build       # Update documentation
git add . && git commit -m "Your changes"

Adding Features

# Add authentication
# Edit Cargo.toml to include "auth" feature
cargo build --features "auth"

# Add content management
cargo build --features "content-db"

# Add everything
cargo build --features "auth,content-db,email,tls"

🔍 Common Tasks

Add a New Page

1. Create client/src/pages/about.rs
2. Add route in client/src/app.rs
3. Document it in book/

Add API Endpoint

1. Add handler in server/src/api/
2. Register route in server/src/main.rs
3. Add types in shared/src/

Style Your App

1. Edit CSS in style/
2. Use Tailwind classes in components
3. Build CSS with npm run build:css

Update Documentation

1. Edit markdown files in book/
2. Build with just docs-build
3. Deploy with just docs-deploy-github

🆘 Troubleshooting

Installation Issues

# Verify setup
just verify-setup

# Common fixes
chmod +x scripts/*.sh  # Fix script permissions
cargo clean && cargo build  # Clean build

Development Issues

# Port already in use
SERVER_PORT=3031 cargo run

# Database connection error
just db-setup  # Setup database

# Build errors
cargo clean && cargo build  # Clean build
just update    # Update dependencies

Documentation Issues

# Documentation won't build
mdbook build  # Check for errors

# Documentation server won't start
just docs-clean && just docs-build  # Clean rebuild

📚 Learning Path

1. Start Here (5 minutes)

• ✅ Run the installer
• ✅ Start development servers
• ✅ Make your first change

2. Explore Features (15 minutes)

• 🔐 Try authentication features
• 📄 Add some content
• 📧 Test email functionality

3. Customize (30 minutes)

• 🎨 Update styling and branding
• 📖 Add documentation sections
• 🔧 Configure for your needs

4. Deploy (15 minutes)

• 🌐 Deploy documentation to GitHub Pages
• 🚀 Deploy app to your platform of choice

🎯 Next Steps

Immediate

1. Customize branding - Update colors, logos, text
2. Add content - Write your app's content
3. Document features - Update documentation

Short-term

1. Database setup - Configure production database
2. Authentication - Set up OAuth providers
3. Email - Configure email service

Long-term

1. Advanced features - Add custom functionality
2. Performance - Optimize for production
3. Monitoring - Set up logging and metrics

🔗 Useful Links

Documentation

• Complete Guide - Full documentation
• Features Guide - Detailed feature documentation
• Installation Guide - Detailed installation instructions

Development

• Leptos Book - Learn Leptos framework
• Axum Documentation - Web server framework
• Just Manual - Task runner documentation

Tools

• mdBook Guide - Documentation system
• Tailwind CSS - CSS framework
• DaisyUI - Component library

💡 Pro Tips

Productivity

• Use just help to discover available commands
• Keep documentation server running while developing
• Use just verify-setup to troubleshoot issues

Best Practices

• Commit early and often
• Document as you build
• Test in different environments
• Keep dependencies updated

Performance

• Use cargo build --release for production
• Enable gzip compression
• Optimize images and assets
• Monitor performance metrics

🎉 You're Ready!

Congratulations! You now have:

• ✅ A fully functional web application
• ✅ Professional documentation system
• ✅ Development environment ready
• ✅ Deployment pipeline configured

Start building something amazing with Rustelo! 🚀

---

Need help? Check the troubleshooting section or visit our complete documentation.

Happy coding! 🦀✨