Rustelo/QUICK_START.md

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

## 🎛️ Essential Commands

### Development
```bash
# 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
```bash
# 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
```bash
# 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:

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

```env
# 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
```bash
# 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)
```bash
# Already configured! Database file created automatically
# Perfect for: Development, testing, small apps
```

### PostgreSQL (Production)
```bash
# 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
```bash
# Deploy documentation
just docs-deploy-github

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

### Check Your Setup
```bash
# View detailed setup information
cat SETUP_COMPLETE.md

# Regenerate setup report
just regenerate-setup-report

# Verify everything is working
just verify-setup
```

### Production Deployment
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Verify setup
just verify-setup

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

### Development Issues
```bash
# 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
```bash
# 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](https://yourusername.github.io/rustelo)** - Full documentation
- **[Features Guide](FEATURES.md)** - Detailed feature documentation
- **[Installation Guide](INSTALL.md)** - Detailed installation instructions

### Development
- **[Leptos Book](https://book.leptos.dev/)** - Learn Leptos framework
- **[Axum Documentation](https://docs.rs/axum/)** - Web server framework
- **[Just Manual](https://github.com/casey/just)** - Task runner documentation

### Tools
- **[mdBook Guide](https://rust-lang.github.io/mdBook/)** - Documentation system
- **[Tailwind CSS](https://tailwindcss.com/)** - CSS framework
- **[DaisyUI](https://daisyui.com/)** - 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](#🆘-troubleshooting) or visit our [complete documentation](https://yourusername.github.io/rustelo).

Happy coding! 🦀✨