Rustelo/book/getting-started/installation.md

Quick Installation

This guide will help you installRustelo 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:

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

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)

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

sudo apt update
sudo apt install git

Linux (RHEL/CentOS/Fedora):

sudo dnf install git
# or for older versions: sudo yum install git

macOS:

# Using Homebrew
brew install git

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

Windows:

# Download from https://git-scm.com/download/win

# Verify installation
git --version

Recommended Tools

1. cargo-leptos

Essential for building Leptos applications:

cargo install cargo-leptos

# Verify installation
cargo leptos --version

2. SQLx CLI

For database migrations and management:

cargo install sqlx-cli --features postgres,sqlite

# Verify installation
sqlx --version

3. Just (command runner)

Optional but recommended for task automation:

cargo install just

# Verify installation
just --version

4. mdBook (for documentation)

If you plan to work with documentation:

cargo install mdbook

# Verify installation
mdbook --version

Installation Methods

Method 1: Clone from Repository (Recommended for Development)

This method gives you the completeRustelo template with all features:

# 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 theRustelo repository on GitHub
2. Click "Use this template"
3. Create your new repository
4. Clone your new repository:

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:

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

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

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

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:

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

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

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:

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

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

# This creates config.toml with all your settings

Verify Installation

1. Check Dependencies

# 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

# Build the project
cargo build

# Build frontend assets
npm run build

# Or use leptos build command
cargo leptos build

3. Run Tests

# Run Rust tests
cargo test

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

4. Start Development Server

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

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

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

3. Configure Features

Enable the features you need by editing your configuration:

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

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

# 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

# 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

# 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

# Test SQLite
sqlite3 database.db ".tables"

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

Permission Issues (Linux/macOS)

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

Performance Issues

If compilation is slow:

# 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 - Configure your application settings
2. First Run & Setup - Get your application running
3. Development Workflow - Learn the development process
4. Project Structure - Understand the codebase organization

Congratulations! You now haveRustelo installed and ready for development. 🎉