Rustelo/info/install.md

Rustelo Installation Guide

Welcome to Rustelo! This guide will help you install and set up your Rust web application framework built with Leptos.

Quick Start

For Unix/Linux/macOS (Development)

# Clone or download the project
git clone <repository-url>
cd rustelo

# Run the simple development installer
./install-dev.sh

For Windows (Development)

# Clone or download the project
git clone <repository-url>
cd rustelo

# Run the PowerShell installer
.\install.ps1

For Production/Advanced Setup

# Full installer with all options
./install.sh --help

# Example production setup
./install.sh -n my-app -e prod --enable-tls

Installation Options

1. Development Setup (Recommended for beginners)

The simplest way to get started:

Unix/Linux/macOS:

./install-dev.sh

Windows:

.\install.ps1

This will:

• Check system requirements
• Install necessary Rust tools
• Create a new project with development defaults
• Set up environment configuration
• Install dependencies and build the project

2. Full Installation (Advanced)

For production deployments or custom configurations:

./install.sh [OPTIONS]

Available Options:

Option	Description	Default
-n, --name NAME	Project name	my-rustelo-app
-e, --env ENV	Environment (dev/prod)	dev
-d, --dir DIR	Installation directory	./<project-name>
-t, --type TYPE	Installation type (full/minimal/custom)	full
--enable-tls	Enable TLS/HTTPS support	false
--enable-oauth	Enable OAuth authentication	false
--disable-auth	Disable authentication features	false
--disable-content-db	Disable content database features	false
--skip-deps	Skip dependency installation	false
--force	Force reinstallation	false
--quiet	Suppress debug output	false
-h, --help	Show help message	-

Examples:

# Basic development setup
./install.sh

# Production blog with HTTPS
./install.sh -n my-blog -e prod --enable-tls

# Minimal installation without auth
./install.sh -t minimal --disable-auth

# Custom installation (interactive)
./install.sh -t custom

# Force reinstall existing project
./install.sh -n existing-project --force

3. Windows PowerShell Installation

For Windows users, use the PowerShell script:

.\install.ps1 [OPTIONS]

PowerShell Options:

Option	Description	Default
-ProjectName	Project name	my-rustelo-app
-Environment	Environment (dev/prod)	dev
-InstallDir	Installation directory	./<project-name>
-EnableTLS	Enable TLS/HTTPS support	false
-EnableOAuth	Enable OAuth authentication	false
-DisableAuth	Disable authentication features	false
-DisableContentDB	Disable content database features	false
-SkipDeps	Skip dependency installation	false
-Force	Force reinstallation	false
-Quiet	Suppress debug output	false
-Help	Show help message	-

PowerShell Examples:

# Basic development setup
.\install.ps1

# Production setup with TLS
.\install.ps1 -ProjectName my-app -Environment prod -EnableTLS

# Custom project location
.\install.ps1 -ProjectName my-blog -InstallDir "C:\Projects\my-blog"

System Requirements

Required Dependencies

• Rust (1.75.0 or later)

  • Install from rustup.rs
  • Includes cargo package manager

• Node.js (18.0.0 or later)

  • Install from nodejs.org
  • Includes npm package manager
  • Optional: pnpm for faster package management

• Git (for cloning repositories)

• OpenSSL (for TLS certificate generation)

Optional Dependencies

• PostgreSQL (for database features)
• Redis (for caching and sessions)
• Docker (for containerized deployment)

System-Specific Requirements

Linux (Ubuntu/Debian)

# Update package list
sudo apt update

# Install required packages
sudo apt install -y git curl build-essential pkg-config libssl-dev

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

macOS

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required packages
brew install git openssl

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install Node.js
brew install node

Windows

1. Install Git from git-scm.com
2. Install Rust from rustup.rs
3. Install Node.js from nodejs.org
4. Install OpenSSL (or use the installer's automatic setup)

Manual Installation

If you prefer to set up the project manually:

1. Clone the Template

git clone <repository-url>
cd rustelo
cp -r template my-project
cd my-project

2. Install Rust Tools

cargo install cargo-leptos
cargo install cargo-watch  # Optional

3. Create Environment Configuration

Create a .env file:

# Environment Configuration
ENVIRONMENT=dev

# Server Configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=3030
SERVER_PROTOCOL=http

# Database Configuration
DATABASE_URL=postgresql://dev:dev@localhost:5432/myapp_dev

# Session Configuration
SESSION_SECRET=your-secret-key-here

# Features
ENABLE_AUTH=true
ENABLE_CONTENT_DB=true
ENABLE_TLS=false

4. Install Dependencies

# Install Rust dependencies
cargo fetch

# Install Node.js dependencies
npm install  # or pnpm install

5. Build the Project

# Build CSS
npm run build:css

# Build Rust code
cargo build

6. Start Development Server

cargo leptos watch

Project Structure

After installation, your project will have this structure:

my-rustelo-app/
├── src/                    # Rust source code
│   ├── client/            # Client-side code
│   ├── server/            # Server-side code
│   └── shared/            # Shared code
├── public/                # Static assets
├── certs/                 # TLS certificates (if enabled)
├── scripts/               # Setup and utility scripts
├── .env                   # Environment configuration
├── Cargo.toml            # Rust dependencies
├── package.json          # Node.js dependencies
├── start.sh              # Development start script
└── start-prod.sh         # Production start script

Configuration

Environment Variables (.env)

Variable	Description	Default
ENVIRONMENT	Environment type (dev/prod)	dev
SERVER_HOST	Server bind address	127.0.0.1
SERVER_PORT	Server port	3030
SERVER_PROTOCOL	Protocol (http/https)	http
DATABASE_URL	Database connection string	PostgreSQL URL
SESSION_SECRET	Session encryption key	Generated
LOG_LEVEL	Logging level	info

Feature Flags

Enable or disable features by setting these variables:

• ENABLE_AUTH - Authentication system
• ENABLE_CONTENT_DB - Content management
• ENABLE_TLS - HTTPS support
• ENABLE_OAUTH - OAuth providers

TLS/HTTPS Configuration

To enable HTTPS:

1. Set ENABLE_TLS=true in .env
2. Set SERVER_PROTOCOL=https in .env
3. Generate certificates:

   ./scripts/generate_certs.sh
   

Development Workflow

Starting the Development Server

# Option 1: Use the start script
./start.sh

# Option 2: Direct command
cargo leptos watch

# Option 3: With CSS watching
npm run dev &
cargo leptos watch

Building for Production

# Option 1: Use the production script
./start-prod.sh

# Option 2: Direct commands
cargo leptos build --release
./target/release/server

Available Commands

Command	Description
cargo leptos watch	Start development server with hot reload
cargo leptos build	Build for production
cargo build	Build Rust code only
npm run build:css	Build CSS only
npm run dev	Watch CSS changes
cargo test	Run tests
cargo clippy	Run linter

Troubleshooting

Common Issues

1. Rust Installation Issues

Error: cargo: command not found

Solution: Ensure Rust is installed and in PATH:

# Add to your shell profile (.bashrc, .zshrc, etc.)
export PATH="$HOME/.cargo/bin:$PATH"
source ~/.bashrc

2. Node.js Dependencies

Error: npm: command not found

Solution: Install Node.js from nodejs.org

3. Build Failures

Error: cargo build fails with linking errors

Solution: Install system dependencies:

# Ubuntu/Debian
sudo apt install build-essential pkg-config libssl-dev

# macOS
xcode-select --install

4. Port Already in Use

Error: Address already in use (os error 48)

Solution: Change the port in .env:

SERVER_PORT=3031

5. Database Connection Issues

Error: Database connection failed

Solution:

1. Install PostgreSQL
2. Create database: createdb myapp_dev
3. Update DATABASE_URL in .env

Getting Help

1. Check the installation log: install.log
2. Run diagnostics: cargo run --bin config_tool -- validate
3. Review configuration: cargo run --bin config_tool -- show
4. Check the documentation files:
   • README.md - General information
   • CONFIG_README.md - Configuration guide
   • DAISYUI_INTEGRATION.md - UI components

Next Steps

After successful installation:

1. Explore the Code: Check out the example components in src/
2. Configure Features: Enable/disable features in .env
3. Set Up Database: Configure PostgreSQL for data persistence
4. Customize Styling: Modify CSS and DaisyUI components
5. Add Authentication: Set up OAuth providers if needed
6. Deploy: Use the production build for deployment

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

For issues and questions:

• Check the troubleshooting section above
• Review the configuration documentation
• Create an issue on the project repository
• Join the community discussions

Happy coding with Rustelo! 🚀