Rustelo/book/getting-started/installation.md

# Quick Installation

<div align="center">
  <img src="../logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
</div>

This guide will help you install[Rustelo](/) and set up your development environment quickly and efficiently.

## Prerequisites

Before installing Rustelo, ensure you have the following prerequisites:

### System Requirements

- **Operating System**: Linux, macOS, or Windows (WSL2 recommended for Windows)
- **Memory**: Minimum 4GB RAM, 8GB+ recommended for comfortable development
- **Storage**: At least 2GB free space for tools and dependencies
- **Internet Connection**: Required for downloading dependencies

### Required Tools

#### 1. Rust Programming Language

Rustelo requires Rust 1.70.0 or later.

**Install Rust using rustup:**

```bash
# Install rustup (Rust installer and version manager)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Follow the on-screen instructions, then restart your shell or run:
source ~/.cargo/env

# Verify installation
rustc --version  # Should be 1.70.0 or later
cargo --version
```

**Update existing Rust installation:**

```bash
rustup update
```

#### 2. Node.js and npm (for frontend assets)

Node.js 18.0.0 or later is required for building frontend assets.

**Option 1: Using Node Version Manager (recommended)**

```bash
# Install nvm (Linux/macOS)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart your shell or run:
source ~/.bashrc

# Install and use Node.js 18
nvm install 18
nvm use 18

# Option 2: Direct installation
# Visit https://nodejs.org/ and download LTS version

# Verify installation
node --version   # Should be 18.0.0 or later
npm --version
```

#### 3. Git

Git is required for version control and dependency management.

**Linux (Ubuntu/Debian):**
```bash
sudo apt update
sudo apt install git
```

**Linux (RHEL/CentOS/Fedora):**
```bash
sudo dnf install git
# or for older versions: sudo yum install git
```

**macOS:**
```bash
# Using Homebrew
brew install git

# Or download from https://git-scm.com/download/mac
```

**Windows:**
```bash
# Download from https://git-scm.com/download/win

# Verify installation
git --version
```

### Recommended Tools

#### 1. cargo-leptos

Essential for building Leptos applications:

```bash
cargo install cargo-leptos

# Verify installation
cargo leptos --version
```

#### 2. SQLx CLI

For database migrations and management:

```bash
cargo install sqlx-cli --features postgres,sqlite

# Verify installation
sqlx --version
```

#### 3. Just (command runner)

Optional but recommended for task automation:

```bash
cargo install just

# Verify installation
just --version
```

#### 4. mdBook (for documentation)

If you plan to work with documentation:

```bash
cargo install mdbook

# Verify installation
mdbook --version
```

## Installation Methods

### Method 1: Clone from Repository (Recommended for Development)

This method gives you the complete[Rustelo](/) template with all features:

```bash
# Clone the repository
git clone https://github.com/yourusername/rustelo.git
cd rustelo

# Copy the template to your project
cp -r template my-rustelo-app
cd my-rustelo-app

# Install dependencies
cargo build

# Install npm dependencies for frontend
npm install
```

### Method 2: Use as Template

Create a new repository using Rustelo as a template:

1. Go to the[Rustelo](/) repository on GitHub
2. Click "Use this template"
3. Create your new repository
4. Clone your new repository:

```bash
git clone https://github.com/yourusername/your-new-app.git
cd your-new-app

# Install dependencies
cargo build
npm install
```

### Method 3: Download and Extract

Download the latest release:

```bash
# Download the latest release
curl -L https://github.com/yourusername/rustelo/archive/main.zip -o rustelo.zip

# Extract
unzip rustelo.zip
cd rustelo-main/template

# Install dependencies
cargo build
npm install
```

## Database Setup

Rustelo supports both SQLite and PostgreSQL. Choose based on your needs:

### Option 1: SQLite (Recommended for Development)

SQLite requires no additional setup and is perfect for development:

```bash
# Set database URL (optional, SQLite is the default)
export DATABASE_URL="sqlite//:database.db"
```

### Option 2: PostgreSQL (Recommended for Production)

#### Option 2a: Using Docker (Easiest)

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

# Set database URL
export DATABASE_URL="postgresql://postgres:password@localhost:5432/rustelo"
```

#### Option 2b: Native Installation

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database
sudo -u postgres createdb rustelo
sudo -u postgres psql -c "CREATE USER rustelo WITH PASSWORD 'password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE rustelo TO rustelo;"
```

**macOS:**
```bash
# Using Homebrew
brew install postgresql
brew services start postgresql

# Create database
createdb rustelo
psql rustelo -c "CREATE USER rustelo WITH PASSWORD 'password';"
psql rustelo -c "GRANT ALL PRIVILEGES ON DATABASE rustelo TO rustelo;"
```

**Windows:**
```bash
# Download and install from https://www.postgresql.org/download/windows/
# Follow the installation wizard
# Use pgAdmin or command line to create database
```

## Environment Configuration

### 1. Create Environment File

Create a `.env` file in your project root:

```bash
cat > .env << EOF
# Database configuration
DATABASE_URL=sqlite//:database.db

# Security secrets (change these!)
SESSION_SECRET=your-session-secret-here
JWT_SECRET=your-jwt-secret-here

# Application settings
RUSTELO_ENV=development
RUSTELO_LOG_LEVEL=debug

# Optional: Email configuration (if using email features)
# SMTP_HOST=smtp.gmail.com
# SMTP_USERNAME=your-email@gmail.com
# SMTP_PASSWORD=your-app-password
# FROM_EMAIL=noreply@yourapp.com
EOF
```

### 2. Generate Secure Secrets

For production or if you want secure development secrets:

```bash
# Generate session secret
openssl rand -base64 32

# Generate JWT secret
openssl rand -base64 32

# Update your .env file with these values
```

### 3. Build Configuration

Generate your application configuration:

```bash
# Build development configuration
./config/scripts/build-config.sh dev

# This creates config.toml with all your settings
```

## Verify Installation

### 1. Check Dependencies

```bash
# Check Rust
rustc --version
cargo --version

# Check Node.js
node --version
npm --version

# Check Git
git --version

# Check optional tools
cargo leptos --version
sqlx --version
just --version
```

### 2. Build Project

```bash
# Build the project
cargo build

# Build frontend assets
npm run build

# Or use leptos build command
cargo leptos build
```

### 3. Run Tests

```bash
# Run Rust tests
cargo test

# Run with all features
cargo test --all-features
```

### 4. Start Development Server

```bash
# Load environment variables
source .env

# Start development server
cargo leptos watch

# Or use just if available
just dev
```

Your application should now be running at `http://localhost:3030`!

## Post-Installation Setup

### 1. Database Migrations

If using a SQL database, run initial migrations:

```bash
# Create initial migration (if not exists)
sqlx migrate add initial

# Run migrations
sqlx migrate run
```

### 2. Create Admin User (Optional)

Some applications may need an initial admin user:

```bash
# This depends on your application setup
cargo run --bin create-admin-user
```

### 3. Configure Features

Enable the features you need by editing your configuration:

```bash
# Edit configuration
./config/scripts/build-config.sh dev

# Enable specific features in config/features/
```

## Development Environment Setup

### 1. IDE Configuration

**VS Code (Recommended):**

Install recommended extensions:
- rust-analyzer
- Leptos Language Server
- TOML Language Support
- SQLx Language Server

**Other IDEs:**
- IntelliJ IDEA with Rust plugin
- Neovim with rust-analyzer
- Emacs with rust-mode

### 2. Git Configuration

Set up Git hooks and configuration:

```bash
# Configure git (if not already done)
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set up pre-commit hooks (optional)
cargo install pre-commit
pre-commit install
```

### 3. Development Tools

Install additional development tools:

```bash
# Code formatting
rustup component add rustfmt

# Linting
rustup component add clippy

# Documentation
cargo install cargo-doc

# Watch for changes
cargo install cargo-watch
```

## Troubleshooting

### Common Installation Issues

#### Rust Installation Problems

```bash
# If rustup installation fails
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- --no-modify-path

# Add to PATH manually
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

#### cargo-leptos Installation Issues

```bash
# If cargo-leptos fails to install
cargo install cargo-leptos --force

# Or install specific version
cargo install cargo-leptos --version 0.2.1
```

#### Database Connection Issues

```bash
# Test SQLite
sqlite3 database.db ".tables"

# Test PostgreSQL
psql $DATABASE_URL -c "SELECT version();"
```

#### Permission Issues (Linux/macOS)

```bash
# If you get permission errors
sudo chown -R $USER:$USER ~/.cargo
chmod -R u+rw ~/.cargo
```

### Performance Issues

If compilation is slow:

```bash
# Use faster linker (Linux)
sudo apt install lld
export RUSTFLAGS="-C link-arg=-fuse-ld=lld"

# Use faster linker (macOS)
export RUSTFLAGS="-C link-arg=-fuse-ld=/usr/bin/ld"

# Increase parallel compilation
export CARGO_BUILD_JOBS=4
```

### Getting Help

If you encounter issues:

1. **Check system requirements** - Ensure you meet all prerequisites
2. **Update tools** - Make sure Rust and other tools are up to date
3. **Check logs** - Look at error messages carefully
4. **Search documentation** - Check the troubleshooting guide
5. **Community support** - Ask questions in forums or chat
6. **GitHub issues** - Report bugs on the repository

## Next Steps

After successful installation:

1. **[Basic Configuration](./configuration.md)** - Configure your application settings
2. **[First Run & Setup](./first-run.md)** - Get your application running
3. **[Development Workflow](../developers/setup/workflow.md)** - Learn the development process
4. **[Project Structure](../developers/setup/structure.md)** - Understand the codebase organization

Congratulations! You now have[Rustelo](/) installed and ready for development. 🎉