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

First Run & Setup

Welcome to your firstRusteloapplication! 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:

# 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

# 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

# Verify your project has the correct structure
ls -la
# Should see: client/, server/, shared/, book/, justfile, Cargo.toml, etc.

3. Environment Configuration

# Check your .env file exists
cat .env
# Should contain: DATABASE_URL, SESSION_SECRET, etc.

4. Dependencies Installed

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

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

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

# 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

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

{
  "success": true,
  "data": {
    "user_id": 1,
    "username": "testuser",
    "email": "test@example.com"
  },
  "message": "User registered successfully"
}

Database Test

# Test database connection
just db-health

# View database tables
just db-status

API Test

# Test API health endpoint
curl http://localhost:3030/api/health

Expected Response:

{
  "status": "healthy",
  "version": "0.1.0",
  "uptime": "00:01:23",
  "database": "connected"
}

🎨 Start the Documentation Server

Rustelo includes a comprehensive documentation system:

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

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

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

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

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

# 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

# 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

# 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

# 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

# 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

# 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

# Set debug level in .env
LOG_LEVEL=debug

# Restart server
just dev

Common Debug Commands

# 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 - Create a complete application
2. Configure Features - Enable additional features
3. Explore Components - 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

# Reset everything
just clean-all
just setup

# Verify setup
just verify-setup

# Check logs
just logs

Documentation Resources

• Troubleshooting Guide - Common issues and solutions
• Configuration Guide - 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!

YourRustelo 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 to create a complete application, or explore Configuration to customize your setup.

Happy coding! 🦀✨