Local Development Setup

Relevant source files

The following files were used as context for generating this wiki page:

• INSTALLATION.md
• requirements.txt
• database.py
• app.py
• CONTRIBUTING.md
• README.md
• SECURITY.md

This guide provides comprehensive instructions for setting up the Smart Absen Face Recognition System for local development. Following these steps will result in a fully functional local instance of the application, connected to a local MySQL database, ready for development and testing. The setup involves configuring the Python environment, installing dependencies, setting up the database, and running the Flask web application.

The project is a Flask-based web application that uses OpenCV and InsightFace for face recognition, and PyMySQL to connect to a MySQL database. For more details on the overall system, see the System Architecture and API Documentation pages.

Prerequisites

Before starting the installation, ensure your development machine meets the following requirements.

Requirement	How to Check	Status
Python 3.8+	python --version	☐
pip (package manager)	pip --version	☐
MySQL Server 8.0+	mysql --version	☐
Git	git --version	☐
Webcam	Device Manager	☐

Sources: INSTALLATION.md:14-23, CONTRIBUTING.md:19-22

Setup Process Overview

The following diagram illustrates the high-level steps required to set up the local development environment.

Sources: INSTALLATION.md, README.md:23-37

Step-by-Step Installation

1. Clone the Repository

First, clone the project repository from GitHub to your local machine.

# Navigate to your projects directory
cd ~/Documents/Projects

# Clone the repository
git clone https://github.com/Fahri-Hilm/Smart_Absen_Facerecognation-2025-Kelompok4.git

# Enter the project directory
cd Smart_Absen_Facerecognation-2025-Kelompok4

Sources: INSTALLATION.md:57-65, CONTRIBUTING.md:26-28

2. Setup Python Environment

It is highly recommended to use a Python virtual environment to isolate project dependencies and avoid conflicts with other projects.

# Create a virtual environment named .venv
python -m venv .venv

# Activate the virtual environment
# On Linux/macOS:
source .venv/bin/activate
# On Windows (Command Prompt):
.venv\Scripts\activate

After activation, your terminal prompt should be prefixed with (.venv).
Sources: INSTALLATION.md:79-95, CONTRIBUTING.md:32-33

3. Install Dependencies

Install all required Python packages using the requirements.txt file.

# Upgrade pip (recommended)
pip install --upgrade pip

# Install all dependencies
pip install -r requirements.txt

The key dependencies for this project are listed below:

Package	Version	Purpose
Flask	≥2.0.0	Web framework for the application backend.
PyMySQL	≥1.0.0	MySQL driver for database connectivity.
opencv-python	≥4.5.0	Used for camera access and face detection.
insightface	≥0.7.0	Provides the high-accuracy ArcFace model for face recognition.
onnxruntime	≥1.10.0	Runtime for executing the InsightFace ONNX model.
python-dotenv	-	Manages environment variables from the .env file.
qrcode	≥7.0	Generates QR codes for cross-device synchronization.

Sources: requirements.txt, INSTALLATION.md:111-125, SECURITY.md:63-68

4. Setup MySQL Database

The application requires a MySQL database to store employee and attendance data.

1. Start the MySQL Service: Ensure your local MySQL server is running.

   # On Linux
   sudo systemctl start mysql
   

2. Create the Database: Log in to MySQL and create a new database.

   -- Login to MySQL as root
   mysql -u root -p
   
   -- Create the database
   CREATE DATABASE absensi_karyawan_db;
   
   -- Verify creation
   SHOW DATABASES;
   
   -- Exit MySQL
   EXIT;
   

Sources: INSTALLATION.md:132-161

5. Configure Application

Application settings, including database credentials, are managed through an .env file.

1. Create the .env file: Copy the example file.

   cp .env.example .env
   

2. Edit the .env file: Update the file with your local database credentials.

   # Database
   DB_HOST=localhost
   DB_USER=root
   DB_PASSWORD=yourpassword
   DB_NAME=absensi_karyawan_db
   
   # App
   SECRET_KEY=your-secret-key
   FLASK_ENV=production
   PORT=5001
   
   # ML Config
   FACE_CONFIDENCE=0.6
   MAX_FACES=1
   

Variable	Description
DB_HOST	The hostname of the MySQL server (usually localhost).
DB_USER	The username for the MySQL database.
DB_PASSWORD	The password for the specified MySQL user.
DB_NAME	The name of the database created in the previous step.
SECRET_KEY	A secret key for Flask session management.
PORT	The port on which the Flask application will run.

Sources: README.md:110-123, CONTRIBUTING.md:43-51, SECURITY.md:10-13

6. Initialize Database Tables

The application automatically creates the necessary database tables upon the first run. This process is handled by the database.py script, which is called from app.py.

The script will create three main tables: admins, employees, and attendance.

The following ER diagram shows the database schema.

Sources: database.py, INSTALLATION.md:200-216

7. Run the Application

Once the setup is complete, you can run the Flask application.

# Ensure the virtual environment is still active
python app.py

You should see output similar to this, indicating the server is running:

 * Serving Flask app 'app'
 * Debug mode: on
 * Running on all addresses (0.0.0.0)
 * Running on http://127.0.0.1:5001
 * Running on http://192.168.x.x:5001

Sources: INSTALLATION.md:219-234

The following sequence diagram shows the application startup process.

Sources: app.py, database.py, SECURITY.md:10-13

Verification

After running the application, verify the installation by accessing the following URLs in your browser:

URL	Expected Result
http://localhost:5001	The main home page appears.
http://localhost:5001/auth	A QR code for authentication is displayed.
http://localhost:5001/admin/login	The admin login form is shown.
http://localhost:5001/web_attendance	The browser prompts for camera access.

The default admin credentials are:

• Username: admin
• Password: admin123

Sources: INSTALLATION.md:237-254

Summary

By following this guide, you have successfully set up a local development environment for the Smart Absen project. You have cloned the repository, configured the Python environment, installed all dependencies, set up and initialized a MySQL database, and launched the Flask application. The system is now running locally on port 5001 and is ready for feature development, bug fixing, and testing.