Skip to main content

Quickstart Guide

Get Visage up and running on your local machine in just a few steps.

Prerequisites​

Before you begin, ensure you have the following installed:

Python 3.9+ 🐍​

Required for the FastAPI backend

Node.js 18+ 📦​

Required for the React frontend

Webcam 📷​

For real-time face detection

Git 🔧​

To clone the repository

Installation​

Step 1: Clone the Repository​

git clone https://github.com/yourusername/visage.git
cd visage

Step 2: Set Up the Backend​

Navigate to the backend directory and install dependencies:

cd backend
python -m venv venv

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

pip install -r requirements.txt

Initialize the database:

python ../scripts/setup_db.py

Step 3: Start the Backend Server​

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

The backend will be available at http://localhost:8000

tip

Visit http://localhost:8000/docs to see the interactive API documentation

Step 4: Set Up the Frontend​

Open a new terminal and navigate to the frontend directory:

cd frontend
npm install

Step 5: Start the Frontend​

npm run dev

The frontend will be available at http://localhost:5173

Step 6: Register Your First Person​

  1. Navigate to http://localhost:5173
  2. Click "Register New Person"
  3. Enter their name and relationship
  4. Allow webcam access
  5. Capture a clear photo of their face
  6. Click "Register"

Registration Flow

Step 7: Test Real-time Identification​

  1. Return to the home page
  2. Click "Start Identification"
  3. Allow webcam access
  4. The system will identify faces in real-time

Identification Flow

Verify Installation​

Run the health check to verify everything is working:

curl http://localhost:8000/api/v1/health

Expected response:

{
  "status": "healthy",
  "service": "visage",
  "version": "1.0.0"
}

Docker Alternative​

Prefer Docker? Run the entire stack with Docker Compose:

docker-compose up -d

This will start:

  • Backend API on http://localhost:8000
  • Frontend on http://localhost:5173
warning

Docker deployment may have issues accessing your webcam. Local development is recommended for full functionality.

Next Steps​

Common Issues​

Backend won't start​

Problem: ModuleNotFoundError or import errors

Solution: Ensure you've activated the virtual environment and installed all dependencies:

source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt

Webcam not detected​

Problem: Browser doesn't detect webcam

Solution:

  • Ensure webcam permissions are granted in your browser
  • Try using HTTPS or localhost (some browsers require secure context)
  • Check if another application is using the webcam

Slow identification​

Problem: Identification takes several seconds

Solution:

  • The first inference loads the model and will be slow
  • Subsequent inferences should be sub-second
  • Consider using a lighter model like Facenet instead of VGG-Face
  • Check CPU/GPU utilization

No matches found​

Problem: System doesn't recognize registered faces

Solution:

  • Ensure good lighting conditions
  • Register multiple photos of the same person
  • Adjust the MATCH_THRESHOLD in configuration
  • Verify embeddings are being stored (check database)