Rustelo/book/getting-started/quick-start.md

Quick Start

Get up and running withRustelo in just a few minutes! This guide will help you create your firstRustelo application with minimal setup.

Prerequisites

Before you begin, ensure you have the following installed:

• Rust (1.75 or later) - Install Rust
• Node.js (18 or later) - Install Node.js
• Git - Install Git

Optional but recommended:

• Docker - For database setup and deployment
• cargo-leptos - For enhanced development experience

30-Second Setup

1. Clone the Template

git clone https://github.com/yourusername/rustelo.git my-app
cd my-app

2. Run the Interactive Setup

./scripts/configure-features.sh

This interactive script will:

• Help you choose which features to enable
• Set up your environment configuration
• Install necessary dependencies
• Initialize your database (if needed)

3. Start Development Server

cargo run

Your application will be available at http://localhost:3030

Manual Setup

If you prefer to configure everything manually:

1. Choose Your Features

Rustelo uses a modular feature system. Choose the combination that fits your needs:

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

# Static website with HTTPS
cargo build --no-default-features --features "tls"

# Authentication-enabled app
cargo build --no-default-features --features "auth"

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

2. Configure Environment

Create a .env file in your project root:

# Basic configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=3030
SERVER_PROTOCOL=http
ENVIRONMENT=DEV
LOG_LEVEL=info

# Database (if using auth or content-db features)
DATABASE_URL=sqlite//:database.db

# JWT (if using auth feature)
JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
JWT_EXPIRATION_HOURS=24

3. Start the Application

cargo run

First Steps

Once your application is running, you can:

Access Your Application

• Frontend: http://localhost:3030
• Health Check: http://localhost:3030/api/health

Explore the Structure

my-app/
├── client/          # Frontend Leptos components
├── server/          # Backend Axum server
├── shared/          # Shared types and utilities
├── content/         # Static content files
├── docs/           # Documentation
├── migrations/     # Database migrations
└── scripts/        # Helper scripts

Try Different Configurations

Static Website

# Stop the current server (Ctrl+C)
cargo run --no-default-features

Perfect for: Marketing sites, documentation, landing pages

Authentication-Enabled

# Requires database setup
cargo run --features "auth"

Perfect for: User portals, SaaS applications

Content Management

# Requires database setup
cargo run --features "content-db"

Perfect for: Blogs, news sites, CMS

Common First Tasks

1. Customize the Homepage

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">"Welcome to My App"</h1>
                    <p class="py-6">"Your awesome application built with Rustelo"</p>
                </div>
            </div>
        </div>
    }
}

2. Add a New Page

Create client/src/pages/about.rs:

use leptos::*;

#[component]
pub fn AboutPage() -> impl IntoView {
    view! {
        <div class="container mx-auto px-4 py-8">
            <h1 class="text-3xl font-bold mb-4">"About Us"</h1>
            <p>"This is our awesome application!"</p>
        </div>
    }
}

Add it to the router in client/src/app.rs:

<Route path="/about" view=AboutPage/>

3. Add Authentication (Optional)

If you enabled the auth feature, you can add login/register forms:

use leptos::*;
use shared::auth::*;

#[component]
pub fn LoginPage() -> impl IntoView {
    let (email, set_email) = create_signal(String::new());
    let (password, set_password) = create_signal(String::new());

    let login_action = create_action(|credentials: &LoginRequest| {
        let credentials = credentials.clone();
        async move {
            // Login logic here
        }
    });

    view! {
        <div class="card w-96 bg-base-100 shadow-xl">
            <div class="card-body">
                <h2 class="card-title">"Login"</h2>
                <div class="form-control">
                    <label class="label">
                        <span class="label-text">"Email"</span>
                    </label>
                    <input
                        type="email"
                        class="input input-bordered"
                        on:input=move |ev| set_email.set(event_target_value(&ev))
                    />
                </div>
                <div class="form-control">
                    <label class="label">
                        <span class="label-text">"Password"</span>
                    </label>
                    <input
                        type="password"
                        class="input input-bordered"
                        on:input=move |ev| set_password.set(event_target_value(&ev))
                    />
                </div>
                <div class="card-actions justify-end">
                    <button
                        class="btn btn-primary"
                        on:click=move |_| {
                            login_action.dispatch(LoginRequest {
                                email: email.get(),
                                password: password.get(),
                            });
                        }
                    >
                        "Login"
                    </button>
                </div>
            </div>
        </div>
    }
}

Database Setup (Optional)

If you're using features that require a database (auth or content-db):

SQLite (Recommended for development)

# Already configured with DATABASE_URL=sqlite:database.db
# The database file will be created automatically

PostgreSQL (Recommended for production)

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

# Update your .env file
DATABASE_URL=postgresql://postgres:password@localhost:5432/rustelo

Run Migrations

# Install sqlx-cli if not already installed
cargo install sqlx-cli

# Run migrations
sqlx migrate run

Development Tips

Hot Reloading

For the best development experience, use cargo-leptos:

# Install cargo-leptos
cargo install cargo-leptos

# Start with hot reloading
cargo leptos serve

Database Inspection

# SQLite
sqlite3 database.db ".tables"

# PostgreSQL
psql postgresql://postgres:password@localhost:5432/rustelo -c "\dt"

Logs and Debugging

# Verbose logging
LOG_LEVEL=debug cargo run

# Trace level (very verbose)
LOG_LEVEL=trace cargo run

Next Steps

Now that you haveRustelo running, here are some suggested next steps:

1. Learn about Features - Understand what each feature provides
2. Project Structure - Get familiar with the codebase
3. Configuration - Configure your application
4. Database Setup - Set up your database properly
5. Deployment - Deploy your application

Troubleshooting

Common Issues

Port already in use:

# Change the port in .env
SERVER_PORT=3031

Database connection error:

# Check if PostgreSQL is running
docker ps

# Or use SQLite instead
DATABASE_URL=sqlite//:database.db

Build errors:

# Clean build
cargo clean && cargo build

# Update dependencies
cargo update

Permission denied on scripts:

chmod +x scripts/configure-features.sh

Getting Help

• Documentation: Check the relevant sections in this book
• Examples: Look at the examples/ directory
• Issues: Search or create an issue on GitHub
• Community: Join our discussions

What's Next?

Congratulations! You now have a workingRustelo application. Here are some recommended next steps:

• Customize the UI: Modify the frontend components to match your design
• Add Business Logic: Implement your application's core functionality
• Set Up Database: Configure your preferred database system
• Add Authentication: Enable user management if needed
• Deploy: Get your application ready for production

Ready to dive deeper? Continue with the Installation guide for more detailed setup instructions.