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

# Quick Start

<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 guide will help you create your first[Rustelo](/) application with minimal setup.

## Prerequisites

Before you begin, ensure you have the following installed:

- **Rust** (1.75 or later) - [Install Rust](https://rustup.rs/)
- **Node.js** (18 or later) - [Install Node.js](https://nodejs.org/)
- **Git** - [Install Git](https://git-scm.com/)

Optional but recommended:
- **Docker** - For database setup and deployment
- **cargo-leptos** - For enhanced development experience

## 30-Second Setup

### 1. Clone the Template

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

### 2. Run the Interactive Setup

```bash
./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

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

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

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

```bash
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
```bash
# Stop the current server (Ctrl+C)
cargo run --no-default-features
```
Perfect for: Marketing sites, documentation, landing pages

#### Authentication-Enabled
```bash
# Requires database setup
cargo run --features "auth"
```
Perfect for: User portals, SaaS applications

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

```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">"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`:

```rust
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`:

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

### 3. Add Authentication (Optional)

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

```rust
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)
```bash
# Already configured with DATABASE_URL=sqlite:database.db
# The database file will be created automatically
```

### PostgreSQL (Recommended for production)
```bash
# 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
```bash
# 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`:

```bash
# Install cargo-leptos
cargo install cargo-leptos

# Start with hot reloading
cargo leptos serve
```

### Database Inspection
```bash
# SQLite
sqlite3 database.db ".tables"

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

### Logs and Debugging
```bash
# Verbose logging
LOG_LEVEL=debug cargo run

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

## Next Steps

Now that you have[Rustelo](/) running, here are some suggested next steps:

1. **[Learn about Features](../features/overview.md)** - Understand what each feature provides
2. **[Project Structure](../development/structure.md)** - Get familiar with the codebase
3. **[Configuration](../configuration/environment.md)** - Configure your application
4. **[Database Setup](../database/overview.md)** - Set up your database properly
5. **[Deployment](../deployment/overview.md)** - Deploy your application

## Troubleshooting

### Common Issues

**Port already in use:**
```bash
# Change the port in .env
SERVER_PORT=3031
```

**Database connection error:**
```bash
# Check if PostgreSQL is running
docker ps

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

**Build errors:**
```bash
# Clean build
cargo clean && cargo build

# Update dependencies
cargo update
```

**Permission denied on scripts:**
```bash
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 working[Rustelo](/) 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](./installation.md) guide for more detailed setup instructions.