jesus/Rustelo

Fork 0

Jesús Pérex c5f607be19

chore: fix links

2025-07-08 21:46:12 +01:00

15 KiB

Raw Permalink Blame History

Rustelo Installation Guide

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

# 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

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

./install.sh -m dev

Environment: dev
TLS: disabled
OAuth: disabled
Authentication: enabled
Content Database: enabled
Optimized for development with debugging

2. Production Mode

./install.sh -m prod

Environment: prod
TLS: enabled by default
OAuth: optional
Authentication: enabled
Content Database: enabled
Optimized for production deployment

3. Custom Mode

./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

# Simple development setup
./install.sh

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

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

Production Setup

# 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

# 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

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

# 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

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

What the Installer Does

System Check: Verifies required tools are installed
Dependency Installation: Installs Rust and Node.js if missing
Rust Tools: Installs cargo-leptos, mdbook, just, and other development tools
Documentation Tools: Installs mdBook plugins for enhanced documentation
Project Creation: Copies template files to new project directory
Configuration: Creates .env file with appropriate settings
Dependencies: Installs Rust and Node.js dependencies
Build: Compiles the project
Scripts: Creates startup scripts for development and production
Documentation Setup: Initializes documentation system
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

# 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

# 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

./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

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

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

# 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

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

Getting Help

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

Manual Installation

If you prefer to set up manually without the installer:

1. Clone Template

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

2. Install Tools

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:

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

cargo fetch
npm install

5. Setup Documentation

./scripts/setup-docs.sh --full

6. Build and Run

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

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! 🚀

15 KiB Raw Permalink Blame History

Rustelo Installation Guide

Quick Start

Unix/Linux/macOS

Windows

Installation Modes

1. Development Mode (default)

2. Production Mode

3. Custom Mode

Command Line Options

Unix/Linux/macOS (install.sh)

Windows (install.ps1)

Environment Variables

Examples

Development Setup

Production Setup

Using Environment Variables

Windows Examples

System Requirements

Required Dependencies

Optional Dependencies

System-Specific Requirements

Linux (Ubuntu/Debian)

macOS

Windows

What the Installer Does

Project Structure

Configuration

Environment Variables (.env)

Feature Configuration

Development Workflow

Starting the Development Server

Building for Production

Available Commands

Development Commands

Just Commands (Task Runner)

Documentation Commands

Troubleshooting

Common Issues

1. Installation Mode Not Recognized

2. Project Directory Already Exists

3. Missing Dependencies

4. Rust Installation Issues

5. Node.js Dependencies

6. Build Failures

Getting Help

Manual Installation

1. Clone Template

2. Install Tools

3. Configure Environment

4. Install Dependencies

5. Setup Documentation

6. Build and Run

Production Deployment

Security Checklist

Environment Variables for Production

Support

License

15 KiB

Raw Permalink Blame History

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

Windows (`install.ps1`)