Rustelo/book/getting-started/first-run.md

# 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! 🦀✨