Installation Guide

Installation Guide: Face + OTP Authentication System

Okay, let's get this running on your laptop. Grab some chai. The whole thing takes about 30 to 45 minutes, and most of that is just waiting for packages to download.

Prerequisites

• Python 3.11 (64-bit). Get it from python.org. Versions 3.9 to 3.12 also work, but MediaPipe won't install on a 32-bit Python, so double-check that. On Windows, tick "Add Python to PATH" during install.
• A webcam. Your laptop's built-in one is fine.
• A C++ build toolchain for dlib. On Windows you can skip this by using the prebuilt wheel in step 3.
• VS Code or any editor you like.
• Chrome or Edge for testing webcam access.
• PostgreSQL 13+ and Docker only if you want production mode. SQLite works out of the box for local development.

Step-by-Step Setup

1. Open the project folder. Extract the zip you downloaded from CodeAj, then open a terminal inside the folder. In VS Code, just use Terminal > New Terminal.
2. Create and activate a virtual environment.

   python -m venv venv
   venv\Scripts\activate

   On macOS or Linux, use source venv/bin/activate instead. You'll see (venv) at the start of your terminal line once it's active.

3. Install dependencies. Windows users, do the dlib part first because it's the one that usually breaks:

   pip install --upgrade pip
   pip install cmake
   pip install dlib-bin
   pip install face_recognition
   pip install -r requirements.txt

   On Linux, run sudo apt install build-essential cmake libopenblas-dev liblapack-dev before this. On macOS, run brew install cmake.

4. Create your .env file.

   copy .env.example .env

   (Use cp on macOS or Linux.)

5. Generate a Fernet key. The app refuses to start without it.

   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

   Copy the output and paste it into .env as FERNET_KEY. While you're in there, set SECRET_KEY to any long random string and keep DB_ENGINE=sqlite.

6. Set up email for OTPs. For testing, the easiest route is printing OTPs to the terminal:

   EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend

   Want real emails? Fill in EMAIL_HOST=smtp.gmail.com, your Gmail address, and a Gmail App Password (not your normal password). Leave SMS_ENABLED=False unless you have Twilio credentials.

7. Run migrations and create an admin.

   python manage.py migrate
   python manage.py createsuperuser

8. Start the server.

   python manage.py runserver

How to Verify It's Working

1. Open http://127.0.0.1:8000/accounts/register/, create an account, and allow camera access when the browser asks. Follow the prompts to capture your face from a few angles.
2. Head to http://127.0.0.1:8000/accounts/login/ and log in. After the password step, the webcam opens and you should get a challenge like "Blink twice".
3. Complete it, and either you land on the dashboard or you get an OTP (check your terminal if you used the console backend).
4. Now try holding up a photo of yourself on your phone. It should fail the liveness check. That's your viva demo right there.
5. Log in as the superuser and open http://127.0.0.1:8000/admin-dashboard/ to see the charts and audit data.
6. Optional: run pytest to confirm the test suite passes.

Common Issues

• "Failed building wheel for dlib": you're trying to compile dlib without a C++ compiler. Run pip uninstall dlib, then pip install dlib-bin. Or install Visual Studio Build Tools with the "Desktop development with C++" workload and try again.
• Webcam doesn't open in the browser: make sure you're on 127.0.0.1 or localhost, since browsers block camera access on plain HTTP from other addresses. Also close Zoom, Teams or anything else using the camera, and check the camera permission icon in the address bar.
• "No matching distribution found for mediapipe": your Python is either 32-bit or outside 3.9 to 3.12. Reinstall a 64-bit Python 3.11 and recreate the virtual environment.
• App crashes on startup mentioning Fernet: FERNET_KEY is missing or got pasted with extra spaces or quotes. Generate a fresh one and paste it cleanly.

Still stuck? Reach out to CodeAj setup support and we'll sort it out on a call.