chore: fix links
This commit is contained in:
Jesús Pérex
parent
095fd89ff7
commit
c5f607be19
GPG Key ID:
9F243E355E0BC939
568
INSTALL.md
Normal file
568
INSTALL.md
Normal file
@ -0,0 +1,568 @@
|
||||
# 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! 🚀
|
||||
442
QUICK_START.md
Normal file
442
QUICK_START.md
Normal file
@ -0,0 +1,442 @@
|
||||
# Rustelo Quick Start Guide
|
||||
<div align="center">
|
||||
<img src="logos/rustelo_dev-logo-h.svg" alt="RUSTELO" width="300" />
|
||||
</div>
|
||||
|
||||
Get up and running with Rustelo in just a few minutes! This comprehensive guide will take you from zero to a fully functional web application with documentation.
|
||||
|
||||
## 🚀 30-Second Setup
|
||||
|
||||
### Prerequisites Check
|
||||
Before starting, ensure you have:
|
||||
- **Git** - Version control
|
||||
- **Internet connection** - For downloading dependencies
|
||||
|
||||
### One-Command Installation
|
||||
```bash
|
||||
# Clone and install everything automatically
|
||||
git clone https://github.com/yourusername/rustelo.git my-app
|
||||
cd my-app
|
||||
./scripts/install.sh
|
||||
```
|
||||
|
||||
That's it! The installer will:
|
||||
- ✅ Install Rust, Node.js, and all required tools
|
||||
- ✅ Install mdBook and Just task runner
|
||||
- ✅ Set up your project with sensible defaults
|
||||
- ✅ Configure documentation system
|
||||
- ✅ Verify everything is working
|
||||
- ✅ Generate a personalized setup report
|
||||
|
||||
## 🎯 What You Get
|
||||
|
||||
After installation, you'll have:
|
||||
|
||||
### 📁 Complete Project Structure
|
||||
```
|
||||
my-app/
|
||||
├── client/ # Frontend Leptos components
|
||||
├── server/ # Backend Axum server
|
||||
├── shared/ # Shared code and types
|
||||
├── book/ # Documentation source (mdBook)
|
||||
├── scripts/ # Helper scripts
|
||||
├── .env # Environment configuration
|
||||
├── justfile # Task runner commands
|
||||
└── book.toml # Documentation configuration
|
||||
```
|
||||
|
||||
### 🛠️ Essential Tools Ready
|
||||
- **Rust** with Cargo - Main development tools
|
||||
- **mdBook** - Documentation system
|
||||
- **Just** - Task runner for easy commands
|
||||
- **cargo-leptos** - Leptos development server
|
||||
|
||||
### 📚 Documentation System
|
||||
- Interactive documentation website
|
||||
- Auto-synced content from your docs
|
||||
- Multiple deployment options
|
||||
- Mobile-friendly design
|
||||
|
||||
### 📋 Setup Report
|
||||
- **SETUP_COMPLETE.md** - Personalized installation summary
|
||||
- Shows exactly what was installed and configured
|
||||
- Includes quick start commands for your specific setup
|
||||
- Updates automatically after any setup changes
|
||||
|
||||
## 🏃♂️ Start Developing
|
||||
|
||||
### 1. Start Development Servers
|
||||
```bash
|
||||
# Start the web application
|
||||
just dev
|
||||
|
||||
# In another terminal, start documentation server
|
||||
just docs-dev
|
||||
```
|
||||
|
||||
### 2. Open Your App
|
||||
- **Web App**: http://localhost:3030
|
||||
- **Documentation**: http://localhost:3000
|
||||
|
||||
### 3. Make Your First Change
|
||||
Edit `client/src/pages/home.rs`:
|
||||
```rust
|
||||
#[component]
|
||||
pub fn HomePage() -> impl IntoView {
|
||||
view! {
|
||||
<div class="hero min-h-screen bg-base-200">
|
||||
<div class="hero-content text-center">
|
||||
<div class="max-w-md">
|
||||
<h1 class="text-5xl font-bold">"Hello, Rustelo!"</h1>
|
||||
<p class="py-6">"Your web app is ready to build amazing things!"</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🎛️ Essential Commands
|
||||
|
||||
### Development
|
||||
```bash
|
||||
# Start development server with hot reload
|
||||
just dev
|
||||
|
||||
# Start documentation server
|
||||
just docs-dev
|
||||
|
||||
# Run tests
|
||||
just test
|
||||
|
||||
# Check code quality
|
||||
just check
|
||||
|
||||
# Build for production
|
||||
just build-prod
|
||||
```
|
||||
|
||||
### Documentation
|
||||
```bash
|
||||
# Setup documentation system
|
||||
just docs-setup
|
||||
|
||||
# Build documentation
|
||||
just docs-build
|
||||
|
||||
# Deploy to GitHub Pages
|
||||
just docs-deploy-github
|
||||
|
||||
# Clean documentation build
|
||||
just docs-clean
|
||||
|
||||
# Show all documentation commands
|
||||
just help-docs
|
||||
```
|
||||
|
||||
### System
|
||||
```bash
|
||||
# Verify installation
|
||||
just verify-setup
|
||||
|
||||
# Show all available commands
|
||||
just help
|
||||
|
||||
# Generate setup completion report
|
||||
just generate-setup-report
|
||||
|
||||
# Update dependencies
|
||||
just update
|
||||
```
|
||||
|
||||
## 🔧 Configuration Options
|
||||
|
||||
### Choose Your Features
|
||||
Rustelo is modular. Choose what you need:
|
||||
|
||||
```bash
|
||||
# Minimal static website
|
||||
cargo build --no-default-features
|
||||
|
||||
# Full-featured app (default)
|
||||
cargo build --features "auth,content-db,email"
|
||||
|
||||
# Production with HTTPS
|
||||
cargo build --features "tls,auth,content-db,email"
|
||||
```
|
||||
|
||||
### Environment Configuration
|
||||
Edit `.env` to customize your setup:
|
||||
|
||||
```env
|
||||
# Basic Configuration
|
||||
SERVER_HOST=127.0.0.1
|
||||
SERVER_PORT=3030
|
||||
ENVIRONMENT=dev
|
||||
|
||||
# Features (true/false)
|
||||
ENABLE_AUTH=true
|
||||
ENABLE_CONTENT_DB=true
|
||||
ENABLE_TLS=false
|
||||
|
||||
# Database (choose one)
|
||||
DATABASE_URL=sqlite:database.db # SQLite (simple)
|
||||
# DATABASE_URL=postgresql://user:pass@localhost:5432/db # PostgreSQL (production)
|
||||
|
||||
# Logging
|
||||
LOG_LEVEL=debug
|
||||
```
|
||||
|
||||
## 📖 Documentation Features
|
||||
|
||||
### What's Included
|
||||
- **📚 Interactive Guide** - Searchable, mobile-friendly documentation
|
||||
- **🔄 Auto-Sync** - Automatically includes your existing docs
|
||||
- **🌐 Multi-Deploy** - GitHub Pages, Netlify, Vercel, Docker
|
||||
- **🎨 Custom Styling** - Branded documentation with your colors
|
||||
- **📱 Mobile-First** - Works perfectly on all devices
|
||||
|
||||
### Customize Documentation
|
||||
```bash
|
||||
# Edit content in book/ directory
|
||||
# Add your own sections in book/SUMMARY.md
|
||||
# Customize styling in book/theme/custom.css
|
||||
|
||||
# Build and preview
|
||||
just docs-build
|
||||
just docs-dev
|
||||
```
|
||||
|
||||
## 🗄️ Database Setup
|
||||
|
||||
### SQLite (Development)
|
||||
```bash
|
||||
# Already configured! Database file created automatically
|
||||
# Perfect for: Development, testing, small apps
|
||||
```
|
||||
|
||||
### PostgreSQL (Production)
|
||||
```bash
|
||||
# Start PostgreSQL with Docker
|
||||
docker run -d -p 5432:5432 \
|
||||
-e POSTGRES_PASSWORD=password \
|
||||
-e POSTGRES_DB=myapp \
|
||||
postgres:15
|
||||
|
||||
# Update .env
|
||||
DATABASE_URL=postgresql://postgres:password@localhost:5432/myapp
|
||||
|
||||
# Run migrations
|
||||
just db-migrate
|
||||
```
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### Quick Deploy to GitHub Pages
|
||||
```bash
|
||||
# Deploy documentation
|
||||
just docs-deploy-github
|
||||
|
||||
# Deploy will be available at:
|
||||
# https://yourusername.github.io/my-app
|
||||
```
|
||||
|
||||
### Check Your Setup
|
||||
```bash
|
||||
# View detailed setup information
|
||||
cat SETUP_COMPLETE.md
|
||||
|
||||
# Regenerate setup report
|
||||
just regenerate-setup-report
|
||||
|
||||
# Verify everything is working
|
||||
just verify-setup
|
||||
```
|
||||
|
||||
### Production Deployment
|
||||
```bash
|
||||
# Build for production
|
||||
just build-prod
|
||||
|
||||
# Deploy with Docker
|
||||
just docker-build
|
||||
just docker-run
|
||||
|
||||
# Or deploy to cloud platform of choice
|
||||
```
|
||||
|
||||
## 🛠️ Development Workflow
|
||||
|
||||
### Daily Development
|
||||
```bash
|
||||
# Morning routine
|
||||
just verify-setup # Verify everything is working
|
||||
just dev # Start development server
|
||||
just docs-dev # Start documentation (separate terminal)
|
||||
|
||||
# Make changes, they auto-reload!
|
||||
|
||||
# Evening routine
|
||||
just test # Run tests
|
||||
just docs-build # Update documentation
|
||||
git add . && git commit -m "Your changes"
|
||||
```
|
||||
|
||||
### Adding Features
|
||||
```bash
|
||||
# Add authentication
|
||||
# Edit Cargo.toml to include "auth" feature
|
||||
cargo build --features "auth"
|
||||
|
||||
# Add content management
|
||||
cargo build --features "content-db"
|
||||
|
||||
# Add everything
|
||||
cargo build --features "auth,content-db,email,tls"
|
||||
```
|
||||
|
||||
## 🔍 Common Tasks
|
||||
|
||||
### Add a New Page
|
||||
1. Create `client/src/pages/about.rs`
|
||||
2. Add route in `client/src/app.rs`
|
||||
3. Document it in `book/`
|
||||
|
||||
### Add API Endpoint
|
||||
1. Add handler in `server/src/api/`
|
||||
2. Register route in `server/src/main.rs`
|
||||
3. Add types in `shared/src/`
|
||||
|
||||
### Style Your App
|
||||
1. Edit CSS in `style/`
|
||||
2. Use Tailwind classes in components
|
||||
3. Build CSS with `npm run build:css`
|
||||
|
||||
### Update Documentation
|
||||
1. Edit markdown files in `book/`
|
||||
2. Build with `just docs-build`
|
||||
3. Deploy with `just docs-deploy-github`
|
||||
|
||||
## 🆘 Troubleshooting
|
||||
|
||||
### Installation Issues
|
||||
```bash
|
||||
# Verify setup
|
||||
just verify-setup
|
||||
|
||||
# Common fixes
|
||||
chmod +x scripts/*.sh # Fix script permissions
|
||||
cargo clean && cargo build # Clean build
|
||||
```
|
||||
|
||||
### Development Issues
|
||||
```bash
|
||||
# Port already in use
|
||||
SERVER_PORT=3031 cargo run
|
||||
|
||||
# Database connection error
|
||||
just db-setup # Setup database
|
||||
|
||||
# Build errors
|
||||
cargo clean && cargo build # Clean build
|
||||
just update # Update dependencies
|
||||
```
|
||||
|
||||
### Documentation Issues
|
||||
```bash
|
||||
# Documentation won't build
|
||||
mdbook build # Check for errors
|
||||
|
||||
# Documentation server won't start
|
||||
just docs-clean && just docs-build # Clean rebuild
|
||||
```
|
||||
|
||||
## 📚 Learning Path
|
||||
|
||||
### 1. Start Here (5 minutes)
|
||||
- ✅ Run the installer
|
||||
- ✅ Start development servers
|
||||
- ✅ Make your first change
|
||||
|
||||
### 2. Explore Features (15 minutes)
|
||||
- 🔐 Try authentication features
|
||||
- 📄 Add some content
|
||||
- 📧 Test email functionality
|
||||
|
||||
### 3. Customize (30 minutes)
|
||||
- 🎨 Update styling and branding
|
||||
- 📖 Add documentation sections
|
||||
- 🔧 Configure for your needs
|
||||
|
||||
### 4. Deploy (15 minutes)
|
||||
- 🌐 Deploy documentation to GitHub Pages
|
||||
- 🚀 Deploy app to your platform of choice
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
### Immediate
|
||||
1. **Customize branding** - Update colors, logos, text
|
||||
2. **Add content** - Write your app's content
|
||||
3. **Document features** - Update documentation
|
||||
|
||||
### Short-term
|
||||
1. **Database setup** - Configure production database
|
||||
2. **Authentication** - Set up OAuth providers
|
||||
3. **Email** - Configure email service
|
||||
|
||||
### Long-term
|
||||
1. **Advanced features** - Add custom functionality
|
||||
2. **Performance** - Optimize for production
|
||||
3. **Monitoring** - Set up logging and metrics
|
||||
|
||||
## 🔗 Useful Links
|
||||
|
||||
### Documentation
|
||||
- **[Complete Guide](https://yourusername.github.io/rustelo)** - Full documentation
|
||||
- **[Features Guide](FEATURES.md)** - Detailed feature documentation
|
||||
- **[Installation Guide](INSTALL.md)** - Detailed installation instructions
|
||||
|
||||
### Development
|
||||
- **[Leptos Book](https://book.leptos.dev/)** - Learn Leptos framework
|
||||
- **[Axum Documentation](https://docs.rs/axum/)** - Web server framework
|
||||
- **[Just Manual](https://github.com/casey/just)** - Task runner documentation
|
||||
|
||||
### Tools
|
||||
- **[mdBook Guide](https://rust-lang.github.io/mdBook/)** - Documentation system
|
||||
- **[Tailwind CSS](https://tailwindcss.com/)** - CSS framework
|
||||
- **[DaisyUI](https://daisyui.com/)** - Component library
|
||||
|
||||
## 💡 Pro Tips
|
||||
|
||||
### Productivity
|
||||
- Use `just help` to discover available commands
|
||||
- Keep documentation server running while developing
|
||||
- Use `just verify-setup` to troubleshoot issues
|
||||
|
||||
### Best Practices
|
||||
- Commit early and often
|
||||
- Document as you build
|
||||
- Test in different environments
|
||||
- Keep dependencies updated
|
||||
|
||||
### Performance
|
||||
- Use `cargo build --release` for production
|
||||
- Enable gzip compression
|
||||
- Optimize images and assets
|
||||
- Monitor performance metrics
|
||||
|
||||
## 🎉 You're Ready!
|
||||
|
||||
Congratulations! You now have:
|
||||
- ✅ A fully functional web application
|
||||
- ✅ Professional documentation system
|
||||
- ✅ Development environment ready
|
||||
- ✅ Deployment pipeline configured
|
||||
|
||||
**Start building something amazing with Rustelo!** 🚀
|
||||
|
||||
---
|
||||
|
||||
Need help? Check the [troubleshooting section](#🆘-troubleshooting) or visit our [complete documentation](https://yourusername.github.io/rustelo).
|
||||
|
||||
Happy coding! 🦀✨
|
||||
56
README.md
56
README.md
@ -17,39 +17,39 @@ A unified, modern, and secure **Rust** platform to build, deploy, and deliver sc
|
||||
|
||||
<!-- toc -->
|
||||
- [🎯 **Core Platform Features**](#complete-feature-matrix)
|
||||
- [🚀 Quick Start](#quick-start)
|
||||
- [🚀 Quick Start](#-quick-start)
|
||||
* [Option 1: One-Command Setup (Recommended)](#option-1-one-command-setup-recommended)
|
||||
* [Option 2: Interactive Configuration](#option-2-interactive-configuration)
|
||||
* [Option 3: Manual Setup](#option-3-manual-setup)
|
||||
- [📦 Optional Features](#%F0%9F%93%A6-optional-features)
|
||||
* [🔒 TLS (`tls`)](#%F0%9F%94%92-tls-tls)
|
||||
* [🔐 Authentication (`auth`) - *Default*](#%F0%9F%94%90-authentication-auth---default)
|
||||
* [📄 Database Content (`content-db`) - *Default*](#%F0%9F%93%84-database-content-content-db---default)
|
||||
* [📧 Email System (`email`) - *Default*](#%F0%9F%93%A7-email-system-email---default)
|
||||
- [🛠️ Common Configurations](#%F0%9F%9B%A0%EF%B8%8F-common-configurations)
|
||||
- [🗄️ Database Support](#%F0%9F%97%84%EF%B8%8F-database-support)
|
||||
- [🔧 Environment Configuration](#%F0%9F%94%A7-environment-configuration)
|
||||
- [🏗️ Project Structure](#%F0%9F%8F%97%EF%B8%8F-project-structure)
|
||||
- [📚 API Endpoints](#%F0%9F%93%9A-api-endpoints)
|
||||
- [🚀 Development](#%F0%9F%9A%80-development)
|
||||
- [🐳 Docker Deployment](#%F0%9F%90%B3-docker-deployment)
|
||||
- [🔒 Security Features](#%F0%9F%94%92-security-features)
|
||||
- [📖 Documentation](#%F0%9F%93%96-documentation)
|
||||
- [🧪 Testing](#%F0%9F%A7%AA-testing)
|
||||
- [📊 Performance Considerations](#%F0%9F%93%8A-performance-considerations)
|
||||
- [🤝 Contributing](#%F0%9F%A4%9D-contributing)
|
||||
- [📄 License](#%F0%9F%93%84-license)
|
||||
- [🆘 Support](#%F0%9F%86%98-support)
|
||||
- [🎯 Use Cases](#%F0%9F%8E%AF-use-cases)
|
||||
- [🔄 Migration Guide](#%F0%9F%94%84-migration-guide)
|
||||
- [🌟 What's Next?](#%F0%9F%8C%9F-whats-next)
|
||||
- [📚 Documentation System](#%F0%9F%93%9A-documentation-system)
|
||||
- [📦 Optional Features](#-optional-features)
|
||||
* [🔒 TLS (`tls`)](#-tls-tls)
|
||||
* [🔐 Authentication (`auth`) - *Default*](#-authentication-auth---default)
|
||||
* [📄 Database Content (`content-db`) - *Default*](#-database-content-content-db---default)
|
||||
* [📧 Email System (`email`) - *Default*](#-email-system-email---default)
|
||||
- [🛠️ Common Configurations](#-common-configurations)
|
||||
- [🗄️ Database Support](#-database-support)
|
||||
- [🔧 Environment Configuration](#-environment-configuration)
|
||||
- [🏗️ Project Structure](#-project-structure)
|
||||
- [📚 API Endpoints](#-api-endpoints)
|
||||
- [🚀 Development](#-development)
|
||||
- [🐳 Docker Deployment](#-docker-deployment)
|
||||
- [🔒 Security Features](#-security-features)
|
||||
- [📖 Documentation](#-documentation)
|
||||
- [🧪 Testing](#-testing)
|
||||
- [📊 Performance Considerations](#-performance-considerations)
|
||||
- [🤝 Contributing](#-contributing)
|
||||
- [📄 License](#-license)
|
||||
- [🆘 Support](#-support)
|
||||
- [🎯 Use Cases](#-use-cases)
|
||||
- [🔄 Migration Guide](#-migration-guide)
|
||||
- [🌟 What's Next?](#-whats-next)
|
||||
- [📚 Documentation System](#-documentation-system)
|
||||
<!-- tocstop -->
|
||||
|
||||
## Complete Feature Matrix
|
||||
## 🚀 Complete Feature Matrix
|
||||
|
||||
<details>
|
||||
<summary> 🚀 click to see details </summary>
|
||||
<summary> click to see details </summary>
|
||||
|
||||
## 🎯 **Core Platform Features**
|
||||
|
||||
@ -277,9 +277,7 @@ A unified, modern, and secure **Rust** platform to build, deploy, and deliver sc
|
||||
**This makes Rustelo a complete platform for building modern web applications with enterprise-grade features out of the box! 🚀
|
||||
</details>
|
||||
|
||||
## Quick Start
|
||||
|
||||
🚀 Quick Start Guide
|
||||
## 🚀 Quick Start
|
||||
|
||||
**New to Rustelo?** Check out our **[Quick Start Guide](QUICK_START.md)** for a complete walkthrough!
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user