# FreeBSD Setup Guide for rmpca
Enterprise-grade route optimization CLI - FreeBSD-specific setup and installation guide.
## Table of Contents
- [System Requirements](#system-requirements)
- [Quick Start](#quick-start)
- [Installation Methods](#installation-methods)
- [CBSD Jail Integration](#cbsd-jail-integration)
- [Configuration](#configuration)
- [Usage Examples](#usage-examples)
- [Troubleshooting](#troubleshooting)
- [Performance Tuning](#performance-tuning)
---
## System Requirements
### Minimum Requirements
- **FreeBSD Version**: 13.0+ (tested on 13.2+)
- **Architecture**: amd64/x86_64
- **Memory**: 512MB RAM minimum, 2GB+ recommended
- **Disk Space**: 100MB for binary + dependencies
### Optional Requirements
- **OpenSSL**: Required only for HTTP features (jail communication)
- **pkgconf**: Required only for HTTP features
---
## Quick Start
### One-Command Setup
```bash
# Clone and setup in one command
git clone https://github.com/your-org/rmpca-rust.git
cd rmpca-rust
cargo build --release
./target/release/rmpca --help
```
### Installation Verification
```bash
# Verify Rust installation
rustc --version
# Should show: rustc 1.70.0 or later
# Verify cargo installation
cargo --version
# Should show: cargo 1.70.0 or later
# Test the binary
./target/release/rmpca --version
# Should show: rmpca 0.1.0
```
---
## Installation Methods
### Method 1: Rustup (Recommended)
**Best for development and latest versions:**
```bash
# Step 1: Install Rustup
# Step 2: Configure PATH
source $HOME/.cargo/env
# Step 3: Verify installation
rustc --version
cargo --version
# Step 4: Build rmpca
cd rmpca-rust
cargo build --release
```
**Advantages:**
- ✅ Latest stable Rust
- ✅ Easy updates via `rustup update`
- ✅ Per-user installation (no sudo needed)
### Method 2: FreeBSD Packages
**Best for production servers:**
```bash
# Step 1: Install Rust via pkg
sudo pkg install -y rust
# Step 2: Verify installation
rustc --version
cargo --version
# Step 3: Build rmpca
cd rmpca-rust
cargo build --release
```
**Advantages:**
- ✅ System-wide installation
- ✅ Easy updates via `pkg upgrade`
- ✅ Consistent with FreeBSD package management
### Method 3: System-Wide Installation
**Install rmpca binary for all users:**
```bash
# Build the binary
cd rmpca-rust
cargo build --release
# Copy to system bin
sudo cp ./target/release/rmpca /usr/local/bin/
sudo chmod +x /usr/local/bin/rmpca
# Verify installation
which rmpca
rmpca --version
```
**Alternative: Local user installation:**
```bash
# Copy to user's bin directory
mkdir -p $HOME/.local/bin
cp ./target/release/rmpca $HOME/.local/bin/
chmod +x $HOME/.local/bin/rmpca
# Add to PATH (add to ~/.profile)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
source ~/.profile
```
---
## System Dependencies
### Optional HTTP Features
**If you need jail communication (most users):**
```bash
# Install OpenSSL and pkgconf
sudo pkg install -y pkgconf openssl
# Verify installation
pkgconf --version
# Should show: pkgconf 1.8.0 or later
pkg info openssl
# Should show OpenSSL package info
```
### Pure Rust Build (No Dependencies)
**If you only need local optimization:**
```bash
# Build without default features
cargo build --release --no-default-features
# This builds without:
# - reqwest (HTTP client)
# - tokio (async runtime)
# But optimization engine still works!
```
---
## CBSD Jail Integration
### Compatibility with Original Shell Scripts
The Rust binary **drop-in replaces** the original shell scripts:
```bash
# Original location of shell scripts
/usr/local/bin/rmpca # Original shell dispatcher
/usr/local/bin/rmpca-optimize # Original optimize script
/usr/local/bin/rmpca-status # Original status script
# Rust binary provides same functionality
/usr/local/bin/rmpca # Rust binary (all-in-one)
```
### Installation in CBSD Environment
```bash
# Build on CBSD host
cd rmpca-rust
cargo build --release
# Install system-wide
sudo cp ./target/release/rmpca /usr/local/bin/
sudo chmod +x /usr/local/bin/rmpca
# Test in CBSD context
rmpca status
rmpca optimize --help
```
### Environment Variable Compatibility
The Rust binary respects the same environment variables as the shell scripts:
```bash
# All three work identically
export RMPCA_EXTRACT_HOST=10.10.0.2
export RMPCA_BACKEND_HOST=10.10.0.3
export RMPCA_OPTIMIZER_HOST=10.10.0.7
rmpca optimize input.geojson
```
---
## Configuration
### Directory Structure
FreeBSD follows standard Unix directory layout:
```bash
~/.config/
└── RouteMaster.toml # User configuration
~/.cache/
└── rmpca/
├── montreal.rmp # Compiled graphs
└── toronto.rmp
/usr/local/bin/
└── rmpca # Binary
```
### Example Configuration
Create `~/.config/RouteMaster.toml`:
```toml
# Network configuration (overrides defaults)
[network]
extract_host = "10.10.0.2"
backend_host = "10.10.0.3"
optimizer_host = "10.10.0.7"
optimizer_port = 8000
timeout_secs = 120
# Optimization profiles
[optimization.profiles.truck]
turn_left_penalty = 3.0
turn_right_penalty = 1.0
turn_u_penalty = 8.0
[optimization.profiles.delivery]
turn_left_penalty = 2.0
turn_right_penalty = 0.5
turn_u_penalty = 6.0
# Caching (FreeBSD paths work correctly)
[caching]
cache_dir = "~/.cache/rmpca"
# Telemetry
[telemetry]
json_logs = false
```
### Configuration Precedence
1. **CLI flags** (highest priority)
```bash
rmpca optimize input.geojson --turn-left 5.0
```
2. **Environment variables**
```bash
export RMPCA_OPTIMIZER_HOST=192.168.1.100
rmpca optimize input.geojson
```
3. **Configuration file** (`~/.config/RouteMaster.toml`)
```toml
[network]
optimizer_host = "192.168.1.100"
```
4. **Hardcoded defaults** (lowest priority)
```toml
optimizer_host = "10.10.0.7"
```
---
## Usage Examples
### Basic Optimization
```bash
# Compile a map once (5-30 seconds)
rmpca compile-map montreal-roads.geojson -o montreal.rmp --stats
# Optimize instantly (1-5 milliseconds!)
rmpca optimize --cache montreal.rmp input-roads.geojson -o optimized.gpx
# Output:
# Graph Statistics:
# Nodes: 12453
# Edges: 18934
# Components: 1
# Avg degree: 3.04
# Max degree: 8
```
### CBSD Jail Status
```bash
# Check all jails and services
rmpca status --health
# Check specific jail
rmpca status --jail rmpca-backend --health
# JSON output for scripts
### Pipeline Processing
```bash
# End-to-end processing
rmpca pipeline \
--bbox -73.59,45.49,-73.55,45.52 \
--source osm \
-o route.gpx \
--turn-left 2.0
# This runs: extract → validate → clean → optimize → export
```
### Property-Based Testing
```bash
# Run all property tests
cargo test --release --tests property_tests
# Run specific property
cargo test prop_distance_is_symmetric
# Run with many random inputs
PROPTEST_CASES=10000 cargo test --release --tests property_tests
```
---
## Performance Tuning
### FreeBSD-Specific Optimizations
#### 1. Use Native Binary
```bash
# Native binary is faster than compatibility mode
cargo build --release
# Avoid --target for better performance
# (FreeBSD target is automatically detected)
```
#### 2. Compiler Optimizations
The `Cargo.toml` already includes optimal settings for FreeBSD:
```toml
[profile.release]
opt-level = 3 # Maximum optimization
lto = true # Link-time optimization
codegen-units = 1 # Single compilation unit
strip = true # Strip debug symbols
```
#### 3. Runtime Performance
```bash
# Enable binary caching (1000x faster)
rmpca compile-map city.geojson -o city.rmp
# Subsequent runs use cached graph
rmpca optimize --cache city.rmp input.geojson
```
### Memory Usage
```bash
# Monitor memory usage
rmpca optimize input.geojson &
pid=$!
top -p $pid -o pid,vsz,rss,command
# Expected memory:
# - Graph construction: 100-500MB
# - Cached graph load: 10-50MB
# - Optimization: 50-200MB
```
---
## Troubleshooting
### Common Issues
#### Issue: "pkgconf not found"
**Problem:** Building with HTTP features fails.
```bash
Could not find openssl via pkg-config:
Could not run `pkg-config --libs --cflags openssl`
```
**Solution:**
```bash
sudo pkg install -y pkgconf openssl
```
#### Issue: "Command not found: rmpca"
**Problem:** Binary not in PATH.
**Solution:**
```bash
# Check installation location
which rmpca
# If not found, add to PATH
export PATH="$HOME/.local/bin:$PATH"
# Or install system-wide:
sudo cp ./target/release/rmpca /usr/local/bin/
```
#### Issue: "Permission denied"
**Problem:** Cannot access configuration files.
**Solution:**
```bash
# Create config directory
mkdir -p ~/.config
chmod 755 ~/.config
# Create config file
touch ~/.config/RouteMaster.toml
chmod 644 ~/.config/RouteMaster.toml
```
#### Issue: "Cannot connect to optimizer"
**Problem:** HTTP communication fails in CBSD environment.
**Solution:**
```bash
# Check jail status
rmpca status --health
# Verify environment variables
echo $RMPCA_OPTIMIZER_HOST
echo $RMPCA_OPTIMIZER_PORT
# Test network connectivity
ping -c 3 $RMPCA_OPTIMIZER_HOST
```
### Debug Mode
```bash
# Enable verbose logging
RUST_LOG=debug rmpca optimize input.geojson
# Enable structured JSON logging
rmpca optimize input.geojson --json
# Check environment
rmpca --version
---
## Updating
### Update Rust Toolchain
```bash
# Using rustup
rustup update stable
rustup self update
# Using pkg
sudo pkg upgrade rust
```
### Update rmpca Binary
```bash
# Update source code
cd rmpca-rust
git pull origin main
# Rebuild binary
cargo build --release
# Replace system binary
sudo cp ./target/release/rmpca /usr/local/bin/
```
### Update Dependencies
```bash
# Update project dependencies
cd rmpca-rust
cargo update
# Update specific dependency
cargo update reqwest
```
---
## Uninstallation
### Remove Binary
```bash
# Remove system-wide installation
sudo rm /usr/local/bin/rmpca
# Or remove user installation
rm $HOME/.local/bin/rmpca
```
### Remove Configuration and Cache
```bash
# Remove configuration
rm ~/.config/RouteMaster.toml
# Remove cache directory
rm -rf ~/.cache/rmpca
```
### Remove Rust Toolchain
```bash
# If using rustup
rustup self uninstall
# If using pkg
sudo pkg remove rust
```
---
## Comparison: Shell vs Rust
| **Startup Time** | 50-200ms | 5-20ms | 10x faster |
| **Optimization (no cache)** | 5-30s | 5-30s | Same |
| **Optimization (with cache)** | N/A | 1-5ms | 1000x faster |
| **Memory Usage** | High (shell+processes) | Low (single binary) | 10x less |
| **Error Handling** | Basic exit codes | Rich with anyhow | Better UX |
| **Configuration** | Environment only | Layered system | More flexible |
| **Testing** | Manual tests | Property-based | More reliable |
---
## Additional Resources
### Project Documentation
- **Main README**: [README.md](README.md)
- **Plan Document**: [Plan](../.claude/plans/crispy-tumbling-parasol.md)
- **API Documentation**: Run `cargo doc --open`
### FreeBSD Resources
- **FreeBSD Handbook**: https://www.freebsd.org/doc/
- **Ports Collection**: https://www.freebsd.org/ports/
- **Rust on FreeBSD**: https://wiki.freebsd.org/Rust
### Support
- **Issues**: https://github.com/your-org/rmpca-rust/issues
- **Discussions**: https://github.com/your-org/rmpca-rust/discussions
---
## System Requirements Summary
### Minimum Requirements
- ✅ **OS**: FreeBSD 13.0+
- ✅ **Architecture**: amd64/x86_64
- ✅ **Memory**: 512MB RAM
- ✅ **Disk**: 100MB
### Recommended Requirements
- ✅ **OS**: FreeBSD 13.2+
- ✅ **Architecture**: amd64/x86_64
- ✅ **Memory**: 2GB+ RAM
- ✅ **Disk**: 1GB+ (for cache)
- ✅ **Optional**: pkgconf + openssl (for HTTP features)
---
## Quick Reference
### Essential Commands
```bash
# Build
cargo build --release
# Help
rmpca --help
rmpca optimize --help
# Version
rmpca --version
# Configuration
rmpca status --health
rmpca logs rmpca-backend
# Testing
cargo test --release
cargo test --tests property_tests
```
### Environment Variables
```bash
# Override network configuration
export RMPCA_EXTRACT_HOST=10.10.0.2
export RMPCA_BACKEND_HOST=10.10.0.3
export RMPCA_OPTIMIZER_HOST=10.10.0.7
# Enable JSON logging
export RMPCA_JSON_LOGS=1
# Enable Lean 4 verification
export RMPCA_LEAN4_VERIFIED=1
```
### Configuration Files
```bash
# Main configuration
~/.config/RouteMaster.toml
# Cache directory
~/.cache/rmpca/
# Example configuration
cp RouteMaster.toml.example ~/.config/RouteMaster.toml
```
---
**Last Updated**: 2024-04-10
**FreeBSD Version**: Tested on 13.2+
**Rust Version**: 1.70.0+