Skip to main content

​
Overview

Before installing Iris, ensure your system meets the following requirements. Iris is built with Rust and leverages OpenCV for high-performance face detection and recognition, requiring specific system-level dependencies.

​
System Requirements

CPU

Modern x86_64 or ARM64 processor2+ cores recommended for production

Memory

Minimum 2GB RAM4GB+ recommended for concurrent requests

Storage

500MB for dependencies and modelsAdditional space for build artifacts

Network

Internet connection requiredFor model downloads and image fetching

​
Required Dependencies

​
Rust Toolchain

Iris requires Rust 2021 edition or later. Install via rustup:
1

Install rustup

Download and install the official Rust toolchain manager:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Follow the on-screen prompts to complete installation.
2

Configure your shell

Add Rust to your PATH (automatically suggested by installer):
source $HOME/.cargo/env
3

Verify installation

Confirm Rust is installed correctly:
rustc --version
cargo --version
Expected output:
rustc 1.75.0 (or later)
cargo 1.75.0 (or later)
Iris uses Cargo.toml edition = “2021”. Ensure your Rust version supports this edition (Rust 1.56+).

​
OpenCV 4.x

OpenCV is the core computer vision library that powers Iris’s face detection and recognition capabilities. Version 4.x is required.
Install OpenCV via Homebrew:
brew install opencv
Verify installation:
brew list opencv
pkg-config --modversion opencv4
If you encounter linking issues, ensure pkg-config can find OpenCV:
export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig:$PKG_CONFIG_PATH"

​
Build Tools

Additional build dependencies required for compilation:
Required for opencv-rust bindings generation.macOS:
xcode-select --install
Linux:
sudo apt install clang llvm-dev libclang-dev
Verify:
clang --version
Used to locate library paths during compilation.macOS:
brew install pkg-config
Linux:
sudo apt install pkg-config
Verify:
pkg-config --version
Required for downloading AI models via setup script.macOS/Linux:
# Usually pre-installed, verify:
curl --version
Install if missing (Linux):
sudo apt install curl

​
Rust Dependencies

Iris uses the following Rust crates (automatically installed via Cargo):
Cargo.toml
[dependencies]
opencv = "0.98.1"              # OpenCV bindings
reqwest = { version = "0.11", features = ["blocking"] }  # HTTP client
anyhow = "1.0"                 # Error handling
serde = { version = "1.0", features = ["derive"] }       # Serialization
axum = "0.7"                   # Web framework
tokio = { version = "1.0", features = ["full"] }         # Async runtime
tower-http = { version = "0.5", features = ["cors"] }    # CORS middleware
governor = "0.6"               # Rate limiting
base64 = "0.21"                # Base64 encoding/decoding
These dependencies will be automatically fetched when you run cargo build. No manual installation required.

​
AI Models

Iris requires two ONNX models from OpenCV Zoo:

YuNet (Face Detection)

File: face_detection_yunet_2023mar.onnxSize: ~360KBPurpose: Detects faces in images

SFace (Face Recognition)

File: face_recognition_sface_2021dec.onnxSize: ~41MBPurpose: Generates 128-dimensional face embeddings
These models are NOT included in the repository due to their size. You must download them during installation (covered in the next section).

​
Network Requirements

​
Port Availability

Ensure port 8080 is available for the API server: 
# Check if port is in use
lsof -i :8080
# or
netstat -an | grep 8080

​
Firewall Configuration

If running in production, configure your firewall to allow:
  • Inbound: TCP port 8080 (or your configured port)
  • Outbound: HTTPS (443) for downloading models and fetching images

​
Optional: Docker

If you prefer containerized deployment, ensure Docker is installed: 
# Install Docker (Linux)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Verify installation
docker --version
Docker deployment simplifies dependency management. See the Docker Setup guide for containerized installation.

​
Verification Checklist

Before proceeding to installation, verify all prerequisites:
1

Rust installed

rustc --version && cargo --version
2

OpenCV installed

pkg-config --modversion opencv4
3

Build tools available

clang --version && pkg-config --version
4

Network connectivity

curl -I https://github.com
All prerequisites met? Proceed to Installation to set up Iris.

​
Troubleshooting

Symptoms: Errors during cargo build related to OpenCV bindings.Solutions:
  • Verify OpenCV 4.x is installed: pkg-config --modversion opencv4
  • Ensure LLVM/Clang is installed: clang --version
  • Set pkg-config path manually: 
    export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"
  • Check opencv-rust troubleshooting: https://github.com/twistedfall/opencv-rust#troubleshooting
Symptoms: rustc or cargo commands not found.Solutions:
  • Reload shell configuration: source $HOME/.cargo/env
  • Add to ~/.bashrc or ~/.zshrc: 
    export PATH="$HOME/.cargo/bin:$PATH"
  • Reinstall rustup: https://rustup.rs/
Symptoms: “Address already in use” error when starting Iris.Solutions:
  • Find the process using the port: 
    lsof -i :8080
  • Kill the process or change Iris’s port in main.rs:151: 
    let port = 3000; // Change from 8080

​
Next Steps

Installation Guide

Clone the repository and download AI models

Docker Setup

Alternative containerized deployment

Build docs developers (and LLMs) love

Get started for freeTalk to us