Codakey
Play
← Back to biopass

How to Deploy & Use biopass

Biopass: Deployment and Usage Guide

Biopass is a modern, multi-modal biometric login solution for Linux, offering face, fingerprint, and future voice authentication. This guide provides comprehensive instructions for its installation, configuration, and use.

1. Prerequisites

Before installing Biopass, ensure your system meets the following requirements:

  • Linux Operating System: Biopass is designed for Linux desktops.
  • Webcam: Required for facial recognition. An IR camera is recommended for enhanced security with anti-spoofing.
  • Fingerprint Reader: Required for fingerprint authentication.
  • Node.js & npm/yarn: For building the frontend.
  • Rust & Cargo: For building the backend (Tauri application).
  • PAM (Pluggable Authentication Modules): Biopass integrates with PAM for system-level authentication.

2. Installation

Biopass is distributed as a desktop application. The easiest way to install it is by downloading the pre-built binaries from the official releases page.

  1. Download the Latest Release: Visit the Biopass Releases page and download the appropriate package for your Linux distribution (e.g., .deb, .rpm, or .AppImage).

  2. Install the Package:

    • For .deb packages (Debian/Ubuntu-based systems): 
      sudo dpkg -i biopass_X.Y.Z_amd64.deb
sudo apt install -f # To install any missing dependencies
    • For .rpm packages (Fedora/RHEL-based systems): 
      sudo rpm -i biopass-X.Y.Z-1.x86_64.rpm
    • For .AppImage: 
      chmod +x Biopass-X.Y.Z.AppImage
./Biopass-X.Y.Z.AppImage
      It's recommended to integrate AppImages with your system for easier launching.

3. Configuration

Biopass is primarily configured through its graphical user interface (GUI). The GUI allows you to manage authentication methods, register biometrics, and set various parameters.

Key Configuration Areas:

  • Authentication Strategy:
    • execution_mode: Choose between sequential or parallel execution of authentication methods.
    • order: Define the order of execution for methods if sequential mode is chosen.
    • pam_enabled: Enable or disable PAM integration for system login.
  • Face Method Configuration:
    • enable: Toggle facial recognition.
    • retries, retry_delay: Configure retry behavior.
    • detection.model, recognition.model: Select the AI models for face detection and recognition. These models must be registered in the models section.
    • anti_spoofing.enable, anti_spoofing.model: Enable liveness detection and select its corresponding AI model.
    • ir_camera.enable, ir_camera.device_id: Configure an IR camera if available.
  • Fingerprint Method Configuration:
    • enable: Toggle fingerprint authentication.
    • retries, retry_delay: Configure retry behavior.
    • fingers: Manage registered fingerprints.
  • Voice Method Configuration (Future):
    • enable: Toggle voice recognition.
    • model: Select the AI model for voice recognition.
  • Model Management:
    • Biopass requires AI models for face detection, recognition, anti-spoofing, and voice. These models are managed within the GUI. You will need to download and register model files.
    • Validation: The application performs validation to ensure selected models are valid and registered. For example, if Face method is enabled, valid detection and recognition models are required. If anti-spoofing is enabled, a valid anti-spoofing model is also required.
    • Biometric Samples: Before enabling a biometric method (Face or Voice), you must capture at least one sample through the GUI.

Configuration Validation Logic (from app/src/components/config/validation.ts):

The application validates your configuration before saving. Here are some key checks:

  • Face Method:
    • Requires valid Face Detection and Recognition models.
    • If Anti-Spoofing is enabled, a valid Anti-Spoofing model is required.
    • At least one face sample must be captured.
  • Voice Method:
    • Requires a valid Voice Recognition model.
    • At least one voice recording must be captured.

4. Build & Run (From Source)

To build and run Biopass from source, you will need the development prerequisites (Node.js, npm/yarn, Rust, Cargo).

  1. Clone the Repository:

    git clone https://github.com/TickLabVN/biopass.git
cd biopass

  2. Install Frontend Dependencies:

    npm install # or yarn install

  3. Run in Development Mode: This will start the Tauri application with hot-reloading for the frontend.

    npm run tauri dev # or yarn tauri dev

    The development server will run on http://localhost:1420.

  4. Build for Production: This will create a production-ready executable package for your system.

    npm run tauri build # or yarn tauri build

    The built artifacts will be located in the src-tauri/target/release directory (e.g., .deb, .rpm, .AppImage).

5. Deployment

Biopass is a desktop application and is deployed by installing its compiled packages on individual Linux machines. There is no server-side deployment in the traditional sense.

Deployment Steps:

  1. Build Production Binaries: Follow the "Build for Production" steps in Section 4 to generate the .deb, .rpm, or .AppImage files.
  2. Distribute: Share the generated packages with your users.
  3. Install: Users can install the packages as described in Section 2.

6. Troubleshooting

  • "Valid Face Detection model is required" / "Valid Voice Recognition model is required":
    • Issue: You've enabled a biometric method but haven't selected a valid AI model for it in the Biopass settings.
    • Solution: Go to the Biopass configuration GUI, navigate to the respective biometric method settings (Face or Voice), and select/download the required AI models. Ensure the model paths are correctly registered.
  • "At least one face sample must be captured":
    • Issue: You've enabled facial recognition but haven't registered any face samples.
    • Solution: Use the Biopass GUI to capture and register at least one face sample.
  • Application fails to launch after installation:
    • Issue: Missing system dependencies.
    • Solution: For .deb packages, run sudo apt install -f to resolve dependencies. For other package types, check your distribution's documentation on resolving missing dependencies for installed software.
  • Biometric device not detected:
    • Issue: The application cannot find your webcam or fingerprint reader.
    • Solution:
      • Ensure the device is properly connected.
      • Check if other applications can access the device.
      • Verify device permissions. You might need to grant Biopass access to /dev/video* for cameras or specific /dev/input/event* devices for fingerprint readers.
  • PAM integration issues (e.g., login screen doesn't show Biopass):
    • Issue: PAM configuration might be incorrect or Biopass's PAM module isn't correctly installed/enabled.
    • Solution: Review Biopass's documentation (if available) or the project's issue tracker for specific PAM setup instructions. Ensure pam_enabled is set to true in the Biopass configuration.
  • Slow performance or high resource usage:
    • Issue: AI model inference can be resource-intensive.
    • Solution:
      • Ensure your system meets the recommended hardware specifications for running AI models.
      • Check for background processes consuming resources.
      • Consider disabling anti-spoofing if resource usage is critical and your threat model allows it (though not recommended for security).
← Project overviewView alternatives to biopass →