Skip to content

Local Lens - Installation & Setup Guid.md

Latest commit

 

History

History
296 lines (226 loc) · 8.32 KB

Local Lens - Installation & Setup Guid.md

File metadata and controls

296 lines (226 loc) · 8.32 KB

Local Lens - Installation & Setup Guide

📋 Prerequisites

For Development

Required Software

Platform-Specific Requirements

Windows
  • Visual Studio Build Tools or Visual Studio Community
  • CMake - Download
macOS
# Install Xcode Command Line Tools
xcode-select --install

# Install required Homebrew packages
# dlib: Required for face recognition (pre-compiled, avoids build issues)
# imagemagick: Required for RAW image processing on macOS
brew install cmake dlib imagemagick

Important for Apple Silicon (M1/M2/M3) Macs with Python 3.12+: The dlib library cannot be built from source on newer macOS/Python combinations due to SDK changes. Installing dlib via Homebrew first resolves this issue. The Python package will then link against the system library.

Linux (Ubuntu/Debian)
sudo apt update
sudo apt install build-essential cmake libopenblas-dev liblapack-dev libx11-dev libgtk-3-dev libwebkit2gtk-4.0-dev
Linux (CentOS/RHEL/Fedora)
sudo dnf install gcc gcc-c++ cmake openblas-devel lapack-devel gtk3-devel webkit2gtk3-devel

For End Users

  • No prerequisites - The distributed application includes all dependencies

🚀 Quick Start

Option 1: Download Pre-built Release (Recommended)

  1. Visit the Releases page
  2. Download the installer for your platform:
    • Windows: Local_Lens_x.x.x_x64-setup.exe or Local_Lens_x.x.x_x64_en-US.msi
    • macOS: Local_Lens_x.x.x_x64.dmg
    • Linux: Local_Lens_x.x.x_amd64.deb or Local_Lens_x.x.x_x86_64.AppImage
  3. Run the installer and follow the setup wizard
  4. Launch Local Lens from your applications menu

Option 2: Build from Source

Follow the Development Setup section below.

💻 Development Setup

1. Clone the Repository

git clone https://github.com/your-username/local-lens.git
cd local-lens

2. Set Up the Python Backend

Create Virtual Environment

cd backend
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

Install Python Dependencies

# Install core dependencies
pip install -r requirements.txt

# Note: face_recognition installation may take 10-15 minutes
# as it compiles dlib from source

Troubleshooting Python Dependencies

If face_recognition installation fails:

Windows:

# Ensure Visual Studio Build Tools are installed
# Try installing dlib separately first:
pip install cmake
pip install dlib
pip install face_recognition

macOS (especially Apple Silicon M1/M2/M3):

# Step 1: Install system dependencies via Homebrew (REQUIRED)
brew install cmake dlib imagemagick

# Step 2: Create and activate a Python 3.11 virtual environment
# (Python 3.11 is recommended for best compatibility)
python3.11 -m venv .venv
source .venv/bin/activate

# Step 3: Upgrade pip and install the rest
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

Note: If you're using Python 3.12+, you MUST install dlib via Homebrew first. The rawpy library is replaced by Wand (ImageMagick) on macOS for RAW image support.

# Ensure development packages are installed
sudo apt install build-essential cmake libopenblas-dev liblapack-dev
pip install dlib
pip install face_recognition

3. Set Up the Frontend

cd ../frontend
pnpm install

4. Development Workflow

You can run the application in two modes during development:

Option 1: Manual Server (Default)

Run the Python backend manually. This is best for developing backend features as you can restart the server quickly.

Terminal 1: Python Backend

cd backend
venv\Scripts\activate  # Windows
# source venv/bin/activate  # macOS/Linux
python main.py

The backend will start on http://127.0.0.1:8000

Terminal 2: Frontend & Tauri

cd frontend
pnpm run tauri dev

This will:

  • Start the Vite development server
  • Launch the Tauri desktop application
  • Enable hot-reload for frontend changes

Option 2: Sidecar Mode (Testing the Executable)

Force Tauri to launch the bundled backend_server executable (sidecar) instead of connecting to localhost:8000. Use this to verify the frozen executable works before building.

Terminal:

# Windows PowerShell
$env:USE_SIDECAR="true"; pnpm run tauri dev

# macOS/Linux
USE_SIDECAR=true pnpm run tauri dev

🔧 Building for Production

Prerequisites Check

Before building, ensure all development dependencies are properly installed:

# Verify Node.js
node --version  # Should be v18+

# Verify Rust
rustc --version

# Verify Python environment
cd backend
venv\Scripts\activate  # Windows
# source venv/bin/activate  # macOS/Linux
python -c "import face_recognition; print('✅ Face recognition ready')"

Step 1: Build Python Backend Executable

cd backend
venv\Scripts\activate  # Windows
# source venv/bin/activate  # macOS/Linux

# Create standalone executable with PyInstaller
python -m PyInstaller backend_server.spec

The executable will be created in backend/dist/backend_server.exe (Windows) or backend/dist/backend_server (macOS/Linux).

Step 2: Copy Backend to Tauri

We have automated this step with a helper script that detects your platform and renames the binary correctly.

cd frontend
node ensure-backend.js

This script will:

  1. Find the built backend_server executable in ../backend/dist/
  2. Copy it to src-tauri/
  3. Rename it to the correct target triple (e.g., backend_server-x86_64-pc-windows-msvc.exe or backend_server-aarch64-apple-darwin)

Note: If you skip this step, the Tauri build will fail because it won't find the sidecar executable.

Step 3: Build Desktop Application

cd frontend

# For local builds you need to load the `.eve` first:
source .env && pnpm run tauri build

# Build production version
pnpm run tauri build

This will create:

  • Windows: .msi and .exe installers in src-tauri/target/release/bundle/
  • macOS: .dmg installer and .app bundle
  • Linux: .deb, .AppImage, or .rpm packages

Build Output Locations

frontend/src-tauri/target/release/bundle/
├── msi/           # Windows MSI installer
├── nsis/          # Windows NSIS installer  
├── dmg/           # macOS disk image
├── macos/         # macOS app bundle
├── deb/           # Debian package
├── appimage/      # Linux AppImage
└── rpm/           # RPM package

⚠️ Important Notes & Troubleshooting

Memory Considerations

  • The AI face recognition uses significant memory. For large photo collections (>1000 photos), ensure at least 8GB RAM
  • The application automatically falls back to less memory-intensive algorithms when needed

Performance Optimization

  • Face recognition is CPU-intensive. Processing time scales with image resolution and number of faces
  • For faster processing, consider resizing very large images before organization

Data Storage

  • Application data is stored in platform-specific locations:
    • Windows: %APPDATA%/LocalLens/
    • macOS: ~/Library/Application Support/LocalLens/
    • Linux: ~/.config/LocalLens/

Common Build Issues

PyInstaller Issues

# Clear PyInstaller cache if build fails
python -m PyInstaller --clean backend_server.spec

# For "module not found" errors, add missing modules:
python -m PyInstaller --hidden-import=missing_module_name ...

Tauri Build Issues

# Clear Tauri build cache
pnpm run tauri clean

# Rebuild node modules if needed
rm -rf node_modules pnpm-lock.yaml
pnpm install

Face Recognition Issues

  • Ensure Visual Studio Build Tools are properly installed on Windows
  • On macOS, you may need to set CMAKE_OSX_ARCHITECTURES=arm64 for Apple Silicon
  • On Linux, install libopenblas-dev and liblapack-dev