Rustelo/INSTALL.md

# Rustelo Installation Guide

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

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

## Quick Start

### Unix/Linux/macOS
```bash
# Clone or download the project
git clone <repository-url>
cd rustelo

# Quick development setup (default)
./install.sh

# Or specify options
./install.sh -m dev -n my-app
```

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

# Quick development setup (default)
.\install.ps1

# Or specify options
.\install.ps1 -Mode dev -ProjectName my-app
```

## Installation Modes

The unified installer supports three modes:

### 1. Development Mode (default)
```bash
./install.sh -m dev
```
- Environment: `dev`
- TLS: disabled
- OAuth: disabled
- Authentication: enabled
- Content Database: enabled
- Optimized for development with debugging

### 2. Production Mode
```bash
./install.sh -m prod
```
- Environment: `prod`
- TLS: enabled by default
- OAuth: optional
- Authentication: enabled
- Content Database: enabled
- Optimized for production deployment

### 3. Custom Mode
```bash
./install.sh -m custom
```
- Interactive configuration selection
- Choose features individually
- Customize all settings

## Command Line Options

### Unix/Linux/macOS (`install.sh`)

| Option | Description | Default |
|--------|-------------|---------|
| `-m, --mode MODE` | Installation mode (dev/prod/custom) | `dev` |
| `-n, --name NAME` | Project name | `my-rustelo-app` |
| `-e, --env ENV` | Environment (dev/prod) | `dev` |
| `-d, --dir DIR` | Installation directory | `./<project-name>` |
| `--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 | - |

### Windows (`install.ps1`)

| Option | Description | Default |
|--------|-------------|---------|
| `-Mode` | Installation mode (dev/prod/custom) | `dev` |
| `-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 | - |

## Environment Variables

You can also configure the installer using environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `INSTALL_MODE` | Installation mode (dev/prod/custom) | `dev` |
| `PROJECT_NAME` | Project name | `my-rustelo-app` |
| `ENVIRONMENT` | Environment (dev/prod) | `dev` |
| `ENABLE_TLS` | Enable TLS (true/false) | `false` |
| `ENABLE_AUTH` | Enable authentication (true/false) | `true` |
| `ENABLE_CONTENT_DB` | Enable content database (true/false) | `true` |
| `ENABLE_OAUTH` | Enable OAuth (true/false) | `false` |
| `SKIP_DEPS` | Skip dependencies (true/false) | `false` |
| `FORCE_REINSTALL` | Force reinstall (true/false) | `false` |
| `QUIET` | Quiet mode (true/false) | `false` |

## Examples

### Development Setup
```bash
# Simple development setup
./install.sh

# Development with custom name
./install.sh -n my-blog

# Development with TLS enabled
./install.sh --enable-tls
```

### Production Setup
```bash
# Production setup with HTTPS
./install.sh -m prod -n my-app

# Production with OAuth enabled
./install.sh -m prod --enable-oauth

# Production in custom directory
./install.sh -m prod -d /opt/my-app
```

### Using Environment Variables
```bash
# Set environment variables
export INSTALL_MODE=prod
export PROJECT_NAME=my-production-app
export ENABLE_TLS=true
export ENABLE_OAUTH=true

# Run installer
./install.sh
```

### Windows Examples
```powershell
# Simple development setup
.\install.ps1

# Production setup with HTTPS
.\install.ps1 -Mode prod -ProjectName my-app -EnableTLS

# Custom interactive setup
.\install.ps1 -Mode custom

# Using environment variables
$env:INSTALL_MODE = "prod"
$env:PROJECT_NAME = "my-app"
.\install.ps1
```

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

- **mdBook** (for documentation)
  - Automatically installed by installer
  - Manual install: `cargo install mdbook`
  - Required for documentation system

- **Just** (task runner)
  - Automatically installed by installer
  - Manual install: `cargo install just`
  - Required for development workflow

### Optional Dependencies

- **PostgreSQL** (for database features)
- **Redis** (for caching and sessions)
- **Docker** (for containerized deployment)
- **mdBook plugins** (for enhanced documentation)
  - `mdbook-linkcheck` - Link validation
  - `mdbook-toc` - Table of contents generation
  - `mdbook-mermaid` - Diagram support
  - Automatically installed by installer

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

## What the Installer Does

1. **System Check**: Verifies required tools are installed
2. **Dependency Installation**: Installs Rust and Node.js if missing
3. **Rust Tools**: Installs `cargo-leptos`, `mdbook`, `just`, and other development tools
4. **Documentation Tools**: Installs mdBook plugins for enhanced documentation
5. **Project Creation**: Copies template files to new project directory
6. **Configuration**: Creates `.env` file with appropriate settings
7. **Dependencies**: Installs Rust and Node.js dependencies
8. **Build**: Compiles the project
9. **Scripts**: Creates startup scripts for development and production
10. **Documentation Setup**: Initializes documentation system
11. **TLS Setup**: Generates self-signed certificates if enabled

## 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
├── book/                  # Documentation source (mdBook)
├── book-output/           # Built documentation
├── certs/                 # TLS certificates (if enabled)
├── scripts/               # Setup and utility scripts
│   ├── setup-docs.sh      # Documentation setup
│   ├── build-docs.sh      # Build documentation
│   ├── deploy-docs.sh     # Deploy documentation
│   └── docs-dev.sh        # Documentation dev server
├── .env                   # Environment configuration
├── Cargo.toml            # Rust dependencies
├── package.json          # Node.js dependencies
├── justfile              # Task runner configuration
├── book.toml             # mdBook configuration
├── start.sh              # Development start script (Unix)
├── start.bat             # Development start script (Windows)
├── start-prod.sh         # Production start script (Unix)
├── start-prod.bat        # Production start script (Windows)
└── build.sh              # Build script (Unix)
```

## Configuration

### Environment Variables (.env)

The installer creates a `.env` file with settings appropriate for your chosen mode:

| Variable | Description | Dev Default | Prod Default |
|----------|-------------|-------------|--------------|
| `ENVIRONMENT` | Environment type | `dev` | `prod` |
| `SERVER_HOST` | Server bind address | `127.0.0.1` | `0.0.0.0` |
| `SERVER_PORT` | Server port | `3030` | `443` |
| `SERVER_PROTOCOL` | Protocol | `http` | `https` |
| `DATABASE_URL` | Database connection | Local PostgreSQL | Production URL |
| `SESSION_SECRET` | Session encryption key | Dev key | Generated |
| `LOG_LEVEL` | Logging level | `debug` | `info` |

### Feature Configuration

Features are controlled by environment variables:

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

## Development Workflow

### Starting the Development Server

```bash
# Navigate to project
cd my-rustelo-app

# Start development server (Unix)
./start.sh

# Start development server (Windows)
.\start.bat

# Or use cargo directly
cargo leptos watch
```

### Building for Production

```bash
# Build for production (Unix)
./start-prod.sh

# Build for production (Windows)
.\start-prod.bat

# Or use cargo directly
cargo leptos build --release
./target/release/server
```

### Available Commands

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

#### Just Commands (Task Runner)
| Command | Description |
|---------|-------------|
| `just dev` | Start development server |
| `just build` | Build project |
| `just test` | Run tests |
| `just docs-dev` | Start documentation dev server |
| `just docs-build` | Build documentation |
| `just docs-deploy-github` | Deploy docs to GitHub Pages |
| `just help` | Show all available commands |
| `just help-docs` | Show documentation commands |

#### Documentation Commands
| Command | Description |
|---------|-------------|
| `./scripts/setup-docs.sh` | Setup documentation system |
| `./scripts/docs-dev.sh` | Start documentation dev server |
| `./scripts/build-docs.sh` | Build documentation |
| `./scripts/deploy-docs.sh` | Deploy documentation |
| `mdbook serve` | Serve documentation locally |
| `mdbook build` | Build documentation manually |

## Troubleshooting

### Common Issues

#### 1. Installation Mode Not Recognized
**Error**: `Invalid installation mode: xyz`

**Solution**: Use valid modes: `dev`, `prod`, or `custom`
```bash
./install.sh -m dev  # Valid
./install.sh -m prod # Valid
./install.sh -m custom # Valid
```

#### 2. Project Directory Already Exists
**Error**: `Project directory already exists`

**Solution**: Use `--force` flag or choose different name
```bash
./install.sh --force  # Overwrite existing
./install.sh -n different-name  # Use different name
```

#### 3. Missing Dependencies
**Error**: `Missing required system tools`

**Solution**: Install missing tools:
```bash
# Ubuntu/Debian
sudo apt install git curl openssl

# macOS
brew install git openssl

# Windows: Install manually from official websites
```

#### 4. Rust Installation Issues
**Error**: `cargo: command not found`

**Solution**: Ensure Rust is installed and in PATH:
```bash
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add to PATH
source ~/.cargo/env
```

#### 5. Node.js Dependencies
**Error**: `npm: command not found`

**Solution**: Install Node.js from [nodejs.org](https://nodejs.org/)

#### 6. 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
```

### Getting Help

1. Check the installation log: `install.log`
2. Review configuration files: `.env`, `Cargo.toml`
3. Validate settings: `cargo run --bin config_tool -- validate`
4. Check documentation files in the project directory

## Manual Installation

If you prefer to set up manually without the installer:

### 1. Clone Template
```bash
git clone <repository-url>
cd rustelo
cp -r template my-project
cd my-project
```

### 2. Install Tools
```bash
cargo install cargo-leptos
cargo install mdbook
cargo install just
cargo install cargo-watch  # Optional
cargo install mdbook-linkcheck  # Optional
cargo install mdbook-toc  # Optional
cargo install mdbook-mermaid  # Optional
```

### 3. Configure Environment
Create `.env` file:
```env
ENVIRONMENT=dev
SERVER_HOST=127.0.0.1
SERVER_PORT=3030
SERVER_PROTOCOL=http
DATABASE_URL=postgresql://dev:dev@localhost:5432/myapp_dev
SESSION_SECRET=your-secret-key
ENABLE_AUTH=true
ENABLE_CONTENT_DB=true
ENABLE_TLS=false
```

### 4. Install Dependencies
```bash
cargo fetch
npm install
```

### 5. Setup Documentation
```bash
./scripts/setup-docs.sh --full
```

### 6. Build and Run
```bash
npm run build:css
cargo build
cargo leptos watch

# Or use just commands
just dev
just docs-dev  # In another terminal for documentation
```

## Production Deployment

### Security Checklist

After running the installer in production mode:

- [ ] Update `SESSION_SECRET` in `.env` with a secure random value
- [ ] Configure proper database connection string
- [ ] Set up valid TLS certificates (replace self-signed ones)
- [ ] Review all security settings in configuration files
- [ ] Configure OAuth providers if enabled
- [ ] Set up proper logging and monitoring
- [ ] Configure firewall rules
- [ ] Set up backup procedures

### Environment Variables for Production

```env
ENVIRONMENT=prod
SERVER_HOST=0.0.0.0
SERVER_PORT=443
SERVER_PROTOCOL=https
DATABASE_URL=postgresql://user:password@host:5432/database
SESSION_SECRET=your-very-secure-random-secret
ENABLE_AUTH=true
ENABLE_CONTENT_DB=true
ENABLE_TLS=true
```

## Support

For issues and questions:
- Check the troubleshooting section above
- Review the configuration documentation
- Check the installation log file
- Create an issue on the project repository

## License

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

---

Happy coding with Rustelo! 🚀