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)
```bash
# Clone or download the project
git clone <repository-url>
cd rustelo

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

### For Windows (Development)
```powershell
# Clone or download the project
git clone <repository-url>
cd rustelo

# Run the PowerShell installer
.\install.ps1
```

### For Production/Advanced Setup
```bash
# 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:**
```bash
./install-dev.sh
```

**Windows:**
```powershell
.\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:

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

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

```powershell
.\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:

```powershell
# 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](https://rustup.rs/)
  - Includes `cargo` package manager

- **Node.js** (18.0.0 or later)
  - Install from [nodejs.org](https://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)
```bash
# 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
```bash
# 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](https://git-scm.com/)
2. Install Rust from [rustup.rs](https://rustup.rs/)
3. Install Node.js from [nodejs.org](https://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

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

### 2. Install Rust Tools

```bash
cargo install cargo-leptos
cargo install cargo-watch  # Optional
```

### 3. Create Environment Configuration

Create a `.env` file:

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

```bash
# Install Rust dependencies
cargo fetch

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

### 5. Build the Project

```bash
# Build CSS
npm run build:css

# Build Rust code
cargo build
```

### 6. Start Development Server

```bash
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:
   ```bash
   ./scripts/generate_certs.sh
   ```

## Development Workflow

### Starting the Development Server

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

```bash
# 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:
```bash
# 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](https://nodejs.org/)

#### 3. Build Failures

**Error**: `cargo build` fails with linking errors

**Solution**: Install system dependencies:
```bash
# 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`:
```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! 🚀