- Overview
- System Architecture
- Technologies Used
- Prerequisites
- Installation and Deployment
- Project Structure
- Local Network Configuration
- System Usage
- Troubleshooting
Comprehensive gym management system that combines a modern React frontend with two specialized Python APIs:
- CRUD API: Complete user management (create, read, update, delete)
- Face Recognition API: Real-time facial recognition using CompreFace
- Frontend: Intuitive user interface with Material-UI
- ✅ Complete CRUD of users with SQLite
- ✅ Facial Recognition in real-time with webcam
- ✅ Self-signed HTTPS Certificates for development
- ✅ Local Network Access from multiple devices
- ✅ Modern Interface with React + TypeScript + Material-UI
- ✅ Documented API with Swagger/FastAPI Docs
- ✅ MJPEG Video Streaming from webcam
┌─────────────────────────────────────────────────────────┐
│ Frontend React │
│ (https://localhost:5173) │
│ TypeScript + Material-UI + Vite │
└──────────────┬─────────────────────┬────────────────────┘
│ │
▼ ▼
┌────────────────────┐ ┌──────────────────────┐
│ CRUD API │ │ Face Recognition API│
│ (Python 32-bit) │ │ (Python 64-bit) │
│ https://localhost: │ │ https://localhost: │
│ 8001 │ │ 8002 │
└──────┬─────────────┘ └──────┬───────────────┘
│ │
▼ ▼
┌─────────────┐ ┌──────────────────┐
│ SQLite DB │ │ CompreFace API │
│ gimnasio.db │ │ Docker Container │
└─────────────┘ │ Port 8000 │
└──────────────────┘
- User accesses frontend → React App (port 5173)
- CRUD operations → Frontend → CRUD API (port 8001) → SQLite
- Face registration → Frontend → Face API (port 8002) → CompreFace (port 8000)
- Live recognition → Webcam → Face API → CompreFace → Frontend
- React 18 - UI Framework
- TypeScript - Type safety
- Vite - Ultra-fast build tool
- Material-UI (MUI) - UI Components
- Emotion - CSS-in-JS
- FastAPI - Modern web framework
- Pydantic - Data validation
- SQLite - Database
- Uvicorn - ASGI server
- PyOpenSSL - SSL certificates
- FastAPI - Web framework
- CompreFace Python SDK - Facial recognition
- OpenCV (cv2) - Video capture
- Uvicorn - ASGI server
- Docker - CompreFace container
- CompreFace - Facial recognition engine
- HTTPS - Self-signed certificates
| Software | Minimum Version | Purpose |
|---|---|---|
| Python 3.8+ (32-bit) | 3.8 | CRUD API |
| Python 3.8+ (64-bit) | 3.8 | Face Recognition API |
| Node.js | 18.x | Frontend |
| npm | 9.x | Package manager |
| Docker Desktop | Latest | CompreFace container |
| Git | Latest | Version control |
- RAM: 8 GB minimum (16 GB recommended)
- CPU: 4 cores minimum
- Webcam: Any USB or integrated webcam
- Disk: 2 GB free space
git clone <REPOSITORY_URL>
cd gym- Install Docker Desktop
- Download from: https://www.docker.com/products/docker-desktop/
- Install and make sure Docker is running
CompreFace is an open-source facial recognition solution developed by Exadel.
Steps:
-
Download the latest version
- Visit: https://github.com/exadel-inc/CompreFace/releases
- Download the
.zipfile from the latest release
-
Extract the file
# Unzip the downloaded file into a folder # Example: C:\CompreFace
-
Run Docker Desktop
- Make sure Docker Desktop is running
-
Open Command Prompt (CMD)
- Windows: Search for "cmd" in the start menu
- Press Enter
-
Navigate to the folder
cd C:\path\where\you\extracted\CompreFace # Example: cd C:\CompreFace
-
Run docker-compose
docker-compose up -d
-
Verify installation
- Open your browser
- Visit: http://localhost:8000/login
# Download the CompreFace image from Docker Hub
docker pull exadel/compreface:latest
# Run the container on port 8000
docker run -d -p 8000:8000 --name compreface exadel/compreface:latest
# Verify it's running
docker psAccess CompreFace:
- Open your browser and visit: http://localhost:8000
- Create an account in the CompreFace web interface (http://localhost:8000)
- Create a new application
- Inside the application, create a "Recognition" service
- Copy the generated API Key
- Update the
apiFace/API/main.pyfile:
# Line 23 in apiFace/API/main.py
API_KEY = "YOUR_API_KEY_HERE" # Replace with your API KeyOfficial CompreFace documentation:
- GitHub: https://github.com/exadel-inc/CompreFace
- Releases: https://github.com/exadel-inc/CompreFace/releases
- Getting Started: https://github.com/exadel-inc/CompreFace?tab=readme-ov-file#getting-started-with-compreface
📘 More information: For detailed instructions and advanced installation options, see the official Getting Started guide.
cd apiCRUD
# Windows - Install Python 32-bit from python.org if you don't have it
# Make sure you have 32-bit python in your PATH
# Create virtual environment with Python 32-bit
py -3-32 -m venv venv32
# Activate the virtual environment
# Windows PowerShell:
.\venv32\Scripts\Activate.ps1
# Windows CMD:
.\venv32\Scripts\activate.bat
# Verify it's Python 32-bit
python -c "import struct; print(struct.calcsize('P') * 8)"
# Should display: 32cd API
pip install -r requirements.txtThis will install:
- FastAPI
- Uvicorn
- Pydantic
- PyOpenSSL
python generar_certificados.pyThis will create the certs/ folder with:
cert.pem- SSL certificatekey.pem- Private key
# With HTTPS (production/local network)
python run_https.py
# The API will be available at:
# - https://localhost:8001
# - https://192.168.x.x:8001 (your local IP)
# - Documentation: https://localhost:8001/docsℹ️ Note: CompreFace SDK and OpenCV require 64-bit Python.
cd apiFace
# Create virtual environment with Python 64-bit
python -m venv venv_compreface
# Activate the virtual environment
# Windows PowerShell:
.\venv_compreface\Scripts\Activate.ps1
# Windows CMD:
.\venv_compreface\Scripts\activate.bat
# Verify it's Python 64-bit
python -c "import struct; print(struct.calcsize('P') * 8)"
# Should display: 64Option A: From PyPI (Recommended)
pip install compreface-sdkOption B: From local source code (if included)
cd compreface-python-sdk
pip install -e .
cd ..📘 More information: For complete SDK documentation, examples, and API reference, visit the official CompreFace Python SDK repository.
cd API
pip install -r requirements.txtThis will install:
- FastAPI
- Uvicorn
- OpenCV (cv2)
- PyOpenSSL
- Other necessary dependencies
python generate_cert.py# With HTTPS (production/local network)
python run_https.py
# The API will be available at:
# - https://localhost:8002
# - https://192.168.x.x:8002 (your local IP)
# - Documentation: https://localhost:8002/docscd frontend
npm installThis will install:
- React 18
- TypeScript
- Vite
- Material-UI (MUI)
- @mui/x-data-grid
- Emotion (CSS-in-JS)
- SSL plugin for Vite
Edit the src/services/api.ts file to configure your local network IPs:
// Line 3-5
const API_BASE_URL =
window.location.hostname === "localhost"
? "https://localhost:8001"
: "https://YOUR_LOCAL_IP:8001"; // Example: 'https://192.168.0.7:8001'
// Line 129-131
const FACE_RECOGNITION_API_URL =
window.location.hostname === "localhost"
? "https://localhost:8002"
: "https://YOUR_LOCAL_IP:8002"; // Example: 'https://192.168.0.7:8002'💡 How to find your local IP:
# Windows PowerShell
ipconfig
# Look for "IPv4 Address" in your active network adapter
# Example output:
# IPv4 Address. . . . . . . . . . . . : 192.168.0.7npm run devThe frontend will be available at:
- Local: https://localhost:5173
- Local Network: https://YOUR_LOCAL_IP:5173
- Example: https://192.168.0.7:5173
Access from other devices:
- On your smartphone/tablet, open the browser
- Visit:
https://YOUR_LOCAL_IP:5173 - Accept the self-signed certificate
gym/
├── README.md # This file
├── .gitignore # Ignore sensitive files
│
├── frontend/ # 🎨 React Application
│ ├── src/
│ │ ├── components/ # Reusable components
│ │ │ ├── UserForm.tsx # User form
│ │ │ ├── UserList.tsx # User list
│ │ │ └── ...
│ │ ├── services/
│ │ │ └── api.ts # API client (CRUD + Face)
│ │ ├── types/
│ │ │ └── User.ts # TypeScript types
│ │ ├── App.tsx # Main component
│ │ └── main.tsx # Entry point
│ ├── public/ # Static files
│ ├── package.json
│ ├── vite.config.ts # Vite + HTTPS configuration
│ └── tsconfig.json
│
├── apiCRUD/ # 🗄️ User Management API
│ ├── venv32/ # Python 32-bit virtual environment
│ ├── gimnasio.db # SQLite database
│ ├── gimnasio_db.usuarios.json # JSON backup
│ ├── crearBDD.py # Script to create DB
│ ├── migrar_a_sqlite.py # Migration script
│ └── API/
│ ├── main.py # Main FastAPI API
│ ├── models.py # Pydantic models
│ ├── database.py # SQLite operations
│ ├── requirements.txt # Python dependencies
│ ├── run_https.py # Run with HTTPS
│ ├── generar_certificados.py # Generate SSL certs
│ ├── certs/ # SSL certificates (generated)
│ └── README.md # CRUD API documentation
│
└── apiFace/ # 📸 Facial Recognition API
├── venv_compreface/ # Python 64-bit virtual environment
├── test.py # Basic tests
├── compreface-python-sdk/ # CompreFace SDK
│ ├── compreface/ # Main package
│ ├── examples/ # Usage examples
│ ├── tests/ # SDK tests
│ ├── webcam_demo/ # Webcam demos
│ ├── setup.py # SDK installation
│ └── README.md
└── API/
├── main.py # Main FastAPI API
├── run_https.py # Run with HTTPS
├── generate_cert.py # Generate SSL certs
├── webcam_demo.html # Standalone webcam demo
├── certs/ # SSL certificates (generated)
├── uploads/ # Uploaded images (temp)
└── README.md # Face API documentation
Location: frontend/
Main components:
- Root component of the application
- Manages global user state
- Implements dark theme with Material-UI
- Handles navigation between views
- Interactive user table with DataGrid
- Filters, search, and sorting
- Configurable pagination
- Actions: Edit, Delete, Facial Recognition
- Complete registration/editing form
- Real-time validations
- Fields: Personal information, membership, contact
- Webcam integration for facial registration
- HTTP client for API communication
- CRUD functions: create, read, update, delete
- Facial recognition functions
- Error handling
Technical features:
- Self-signed HTTPS certificates with
@vitejs/plugin-basic-ssl - Local network exposure with
host: '0.0.0.0' - Fixed port: 5173
Location: apiCRUD/API/
Main endpoints:
| Method | Endpoint | Description |
|---|---|---|
| GET | / |
API information |
| POST | /usuarios |
Create new user |
| GET | /usuarios |
List all users |
| GET | /usuarios/{id} |
Get user by ID |
| PUT | /usuarios/{id} |
Update user |
| DELETE | /usuarios/{id} |
Delete user |
| GET | /usuarios/{id}/membresia |
Membership status |
Data models (Pydantic):
class UsuarioCreate:
nombre: str
apellido: str
codigo: Optional[str]
departamento: str
fecha_nacimiento: Optional[str]
fecha_inicio: str
fecha_fin: str
celular: Optional[str]
email: Optional[str]
direccion: Optional[str]
tipo_documento: Optional[str]
numero_documento: Optional[str]SQLite database:
- File:
gimnasio.db - Table:
usuarios - Automatic timestamps:
created_at,updated_at
HTTPS configuration:
- Port: 8001
- Certificates:
certs/cert.pemandcerts/key.pem - Host:
0.0.0.0(accessible on local network)
Location: apiFace/API/
Main endpoints:
| Method | Endpoint | Description |
|---|---|---|
| GET | / |
Service status |
| GET | /health |
Health check |
| POST | /add_faces/ |
Add user faces |
| POST | /webcam/start |
Start webcam capture |
| POST | /webcam/stop |
Stop webcam capture |
| GET | /webcam/status |
Webcam status |
| GET | /webcam/stream |
MJPEG video stream |
| GET | /webcam/recognition |
JSON recognition data |
CompreFace integration:
from compreface import CompreFace
from compreface.service import RecognitionService
compre_face = CompreFace("http://localhost", "8000")
recognition = compre_face.init_face_recognition(API_KEY)
face_collection = recognition.get_face_collection()Features:
- Face registration: Upload multiple images of a user
- Real-time recognition: Detect and recognize faces from webcam
- Video streaming: Send frames to frontend in MJPEG format
- Subject management: Add, update, delete faces in CompreFace
HTTPS configuration:
- Port: 8002
- Certificates:
certs/cert.pemandcerts/key.pem - Host:
0.0.0.0(accessible on local network)
Docker Image: exadel/compreface:latest
Installation:
# Option 1: From Docker Hub (recommended)
docker pull exadel/compreface:latest
docker run -d -p 8000:8000 --name compreface exadel/compreface:latest
# Option 2: From GitHub (development)
git clone https://github.com/exadel-inc/CompreFace.git
cd CompreFace
docker-compose up -dAccess:
Configuration:
- Create account in the web UI
- Create an application
- Create a "Recognition" service
- Copy the API Key
- Update
apiFace/API/main.pywith the API Key
Resources:
- GitHub: https://github.com/exadel-inc/CompreFace
- Documentation: https://github.com/exadel-inc/CompreFace/tree/master/docs
- API Reference: https://github.com/exadel-inc/CompreFace/blob/master/docs/Rest-API-description.md
# Windows PowerShell
ipconfig
# Look for your IPv4 in the active network adapter
# Example: 192.168.0.7Allow traffic on ports: 5173, 8001, 8002, 8000
# Windows PowerShell (run as Administrator)
New-NetFirewallRule -DisplayName "Gym App - Frontend" -Direction Inbound -LocalPort 5173 -Protocol TCP -Action Allow
New-NetFirewallRule -DisplayName "Gym App - API CRUD" -Direction Inbound -LocalPort 8001 -Protocol TCP -Action Allow
New-NetFirewallRule -DisplayName "Gym App - API Face" -Direction Inbound -LocalPort 8002 -Protocol TCP -Action Allow
New-NetFirewallRule -DisplayName "Gym App - CompreFace" -Direction Inbound -LocalPort 8000 -Protocol TCP -Action AllowEdit frontend/src/services/api.ts:
const API_BASE_URL =
window.location.hostname === "localhost"
? "https://localhost:8001"
: "https://192.168.0.7:8001"; // ⚠️ Replace with your IP
const FACE_RECOGNITION_API_URL =
window.location.hostname === "localhost"
? "https://localhost:8002"
: "https://192.168.0.7:8002"; // ⚠️ Replace with your IPOn your smartphone, tablet, or other computer on the same network:
- Open the browser
- Visit:
https://YOUR_LOCAL_IP:5173- Example:
https://192.168.0.7:5173
- Example:
- Accept the self-signed certificate
- Chrome: "Advanced" → "Continue to..."
- Safari iOS: May require installing the certificate
Available URLs:
| Service | Local URL | Network URL |
|---|---|---|
| Frontend | https://localhost:5173 | https://192.168.0.7:5173 |
| CRUD API | https://localhost:8001 | https://192.168.0.7:8001 |
| Face API | https://localhost:8002 | https://192.168.0.7:8002 |
| CompreFace | http://localhost:8000 | http://192.168.0.7:8000 |
- Access the frontend: https://localhost:5173
- Click the "+ New User" button
- Complete the form:
- Personal Information: Name, Last Name, Gender, Date of Birth
- Membership: Code (optional), Department, Start/End Dates
- Contact: Phone, Email, Address
- Identification: Document Type and Number
- Click "Save User"
- In the user list, locate the newly created user
- Click the "Face ID" icon 📷
- The facial recognition dialog will open
- Click "Start Camera"
- Allow webcam access
- Position your face in the center of the camera
- Click "Capture Photo" several times (5-10 photos)
- Tip: Capture from different angles and expressions
- Click "Send Photos"
- Wait for success confirmation
- In the main menu, click "Facial Recognition"
- Click "Start Recognition"
- The camera will activate automatically
- A box will appear around detected faces
- If the face is registered, you'll see:
- User name
- Similarity percentage
- Green color (recognized) or red (unknown)
- In the user list, click the "Edit" icon ✏️
- Modify the necessary fields
- Click "Update User"
- In the user list, click the "Delete" icon 🗑️
- Confirm deletion
- The user will be deleted from the database
- Use the search field at the top of the table
- Filter by:
- Name
- Last Name
- Code
- Department
- Sort columns by clicking the headers
Visit: https://localhost:8001/docs
Here you can:
- View all available endpoints
- Test requests directly from the browser
- View data schemas with examples
- Download OpenAPI specification
Visit: https://localhost:8002/docs
Features:
- Test facial recognition endpoints
- Upload test images
- View real-time responses
- Parameter documentation
Problem: The frontend cannot communicate with the APIs.
Solutions:
-
Verify the APIs are running:
# In each terminal, you should see: # CRUD API: INFO: Uvicorn running on https://0.0.0.0:8001 # Face API: INFO: Uvicorn running on https://0.0.0.0:8002
-
Verify URLs in
frontend/src/services/api.ts:- Make sure to use
https://(nothttp://) - Verify the IP is correct if accessing from another device
- Make sure to use
-
Accept HTTPS certificates:
- Manually visit: https://localhost:8001/docs
- Accept the self-signed certificate
- Repeat for: https://localhost:8002/docs
Problem: When running run_https.py a certificate error appears.
Solution:
# For CRUD API
cd apiCRUD/API
python generar_certificados.py
# For Face API
cd apiFace/API
python generate_cert.pyVerify the files were created:
certs/cert.pemcerts/key.pem
Problem: The Face API cannot connect to CompreFace.
Solutions:
-
Verify the container is running:
docker ps # Should show: exadel/compreface -
If not running, start it:
docker start compreface # Or if it doesn't exist: docker run -d -p 8000:8000 --name compreface exadel/compreface:latest -
Verify access:
- Open: http://localhost:8000
- You should see the CompreFace web interface
-
Verify API Key:
- Edit
apiFace/API/main.py - Line 23:
API_KEY = "YOUR_API_KEY"
- Edit
Problem: The webcam doesn't activate or an error appears.
Solutions:
-
Verify permissions:
- Windows: Settings → Privacy → Camera
- Allow camera access for your browser
-
Close other applications using the camera:
- Zoom, Teams, Skype, etc.
-
Use HTTP instead of HTTPS (development only):
cd apiFace/API uvicorn main:app --host 0.0.0.0 --port 8002 --reload- Then update the frontend to use
http://localhost:8002
- Then update the frontend to use
-
Check the logs:
# In the Face API terminal, look for: INFO: Webcam started successfully
Problem: When installing dependencies, an architecture-related error appears.
Solution:
For CRUD API (32-bit):
# Verify Python version
python -c "import struct; print(struct.calcsize('P') * 8)"
# Should display: 32
# If it displays 64, install Python 32-bit from:
# https://www.python.org/downloads/windows/
# Look for "Windows installer (32-bit)"
# Then create venv with:
py -3-32 -m venv venv32For Face API (64-bit):
# Verify Python version
python -c "import struct; print(struct.calcsize('P') * 8)"
# Should display: 64
# If it displays 32, use:
py -3 -m venv venv_comprefaceProblem: When running npm run dev a module not found error appears.
Solution:
cd frontend
# Delete node_modules and reinstall
rm -rf node_modules
rm package-lock.json
npm install
npm run devProblem: A CORS error appears in the browser console.
Solution:
-
Verify the APIs have CORS enabled:
- In
apiCRUD/API/main.pyandapiFace/API/main.py - There should be:
app.add_middleware( CORSMiddleware, allow_origins=["*"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"], )
- In
-
For production, specify origins:
allow_origins=[ "https://localhost:5173", "https://192.168.0.7:5173", # Your IP ],
Problem: When starting a service, the port is already in use.
Solution:
# Windows PowerShell
# Find the process using the port (example: 8001)
netstat -ano | findstr :8001
# Note the PID (last column)
# Kill the process:
taskkill /PID <PID> /F
# Example:
# taskkill /PID 12345 /Fcd frontend
npm update
npm audit fix# Activate corresponding virtual environment
pip list --outdated
pip install --upgrade <package>cd apiCRUD
# Create backup
cp gimnasio.db gimnasio_backup_$(date +%Y%m%d).db
# Export to JSON
python crearBDD.pyEnable detailed logs:
# In main.py of any API
import logging
logging.basicConfig(level=logging.DEBUG)View Docker logs (CompreFace):
docker logs compreface
docker logs -f compreface # Follow modeSelf-signed certificates are for development only. For production:
-
Get valid certificates:
- Let's Encrypt (free): https://letsencrypt.org/
- Cloudflare SSL
- Hosting provider
-
Configure environment variables:
# Don't put API Keys in code import os API_KEY = os.getenv("COMPREFACE_API_KEY")
-
Restrict CORS:
allow_origins=[ "https://yourdomain.com", ],
-
Use a reverse proxy:
- Nginx
- Apache
- Traefik
To contribute to the project:
- Fork the repository
- Create a branch for your feature:
git checkout -b feature/new-feature - Commit your changes:
git commit -am 'Add new feature' - Push to the branch:
git push origin feature/new-feature - Create a Pull Request
Copyright © 2026 Vito's Gym Club. All rights reserved.
If you encounter problems or have questions:
- Review the Troubleshooting section
- Check the API documentation:
- CRUD API: https://localhost:8001/docs
- Face API: https://localhost:8002/docs
- Review project issues on GitHub
- Contact the development team
- CompreFace - Facial recognition system: https://github.com/exadel-inc/CompreFace
- FastAPI - Modern web framework: https://fastapi.tiangolo.com/
- React - UI library: https://react.dev/
- Material-UI - UI components: https://mui.com/
🏋️ Vito's Gym Club - Comprehensive Management System
Developed with ❤️ to improve our members' experience