Add Windows, XAMPP, and hosted deployment compatibility

.env.example

@@ -0,0 +1,14 @@
+# Local XAMPP defaults. Do not commit real credentials.
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_NAME=fingerprint
+DB_USER=root
+DB_PASSWORD=
+
+# XAMPP + local Docker:
+FP_CLIENT_SERVICE_HOST=http://127.0.0.1:5555
+FP_CLIENT_TIMEOUT=15
+DIAGNOSTICS_ENABLED=1
+
+# Hosted PHP example (use a private HTTPS service):
+# FP_CLIENT_SERVICE_HOST=https://fingerprint-service.example.com

.github/ISSUE_TEMPLATE/compatibility.yml

@@ -0,0 +1,53 @@
+name: Compatibility report
+description: Report Windows, XAMPP, reader, Docker, or hosted-deployment failures
+title: "[Compatibility]: "
+labels: ["compatibility"]
+body:
+  - type: markdown
+    attributes:
+      value: Do not attach fingerprint samples, database passwords, tokens, or unredacted production logs.
+  - type: input
+    id: windows
+    attributes:
+      label: Windows edition and build
+      description: Run winver and include the complete edition, version and OS build.
+    validations:
+      required: true
+  - type: input
+    id: php
+    attributes:
+      label: XAMPP and PHP versions
+    validations:
+      required: true
+  - type: dropdown
+    id: deployment
+    attributes:
+      label: Deployment profile
+      options:
+        - XAMPP and Docker on the same Windows PC
+        - Hosted PHP/MySQL and hosted fingerprint service
+        - Shared PHP hosting and external fingerprint service
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Redacted diagnostics
+      description: Include the diagnostics endpoint, windows-preflight.ps1, docker compose ps, and relevant container logs.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: browser
+    attributes:
+      label: Browser and reader status
+      description: Include browser/version, console errors, whether Device Manager sees the reader, and whether the DigitalPersona Web SDK service is running.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: Steps to reproduce
+    validations:
+      required: true

.github/workflows/compatibility.yml

@@ -0,0 +1,25 @@
+name: Compatibility checks
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  php-and-compose:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        php: ['8.2', '8.3', '8.4']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          extensions: mysqli
+      - name: Lint application PHP
+        run: find . -path './src/core/helpers/Requests' -prune -o -path './fingerprint_service/thirdparty' -prune -o -name '*.php' -print0 | xargs -0 -n1 php -l
+      - name: Validate Compose configuration
+        run: docker compose -f fingerprint_service/docker-compose.yml config --quiet

.gitignore

@@ -1 +1,3 @@
 *.idea
+configs.local.php
+.env

README.md

@@ -23,6 +23,22 @@ the only way to interact with the fingerprint software engine was to use C++, ja
 ### The Solution
 We wrap the fingerprint engine with [grpc](https://grpc.io/) and [protobuf](https://developers.google.com/protocol-buffers/). This allows us to use the engine in any language supported by grpc and there are quite a lot of them. But this is not what this codebase is about. You can find the link to the grpc codebase [here](https://github.com/Bexils/grpc-fingerprint-engine). I realized most people just needed a solution they could plugin to their codebase and forget about it and hence why this codebase was created. It's an abstraction of the grpc solution, completely containerized with docker that can be setup and ready to use with just a few commands. This solution setup a web services on your local machine or server that can be used to make enrollment and verification requests.
 ## Getting started
+This repository contains a Windows browser-capture layer, a PHP/MySQL example
+application, and a Dockerized Linux matching service. They must all be working;
+installing Windows Pro or XAMPP alone is not sufficient.
+
+Choose a deployment profile before starting:
+
+- **Local XAMPP:** PHP, MySQL and Docker run on the Windows capture computer.
+- **Hosted:** the Windows computer captures fingerprints, while PHP, MySQL and
+  the private matching service run on the server.
+- **Shared hosting:** supported only when the host permits PHP to reach a
+  separately deployed matching service.
+
+See [the compatibility guide](docs/COMPATIBILITY.md) for complete setup steps
+and [troubleshooting](docs/TROUBLESHOOTING.md) for diagnostic commands. Read
+[the security notice](SECURITY.md) before handling real biometric data.
+
 ### Download SDK (Mandatory)
 Note: the SDK below is for windows only. Considering most people will be using the scanner on windows (i.e the frontend or client side), if you are already able to capture fingerprint with the device you don't even need this. The solution for the backend enrollment and verification service doesn't require any of this, as it's already packaged in the container.
 
@@ -34,7 +50,8 @@ SDK v3 [Download](https://drive.google.com/open?id=1Hg3HAqwLuqmi9F4eUAgb5WaeLyJv
 SDKPatch [Download](https://drive.google.com/file/d/1yB0oW3NtBfCBKFHSe0Blc7B7grMD854W/view?usp=sharing)
 
 ### Setup the web service (Mandatory for all users)
-Regardless of where you need to set this up, you will have to install docker, which is very easy to do.
+The fingerprint matching service requires Docker unless you provide a compatible
+remote service. A shared hosting account generally cannot run this container.
 
 ### Install Docker for Windows (Mandatory for windows users)
 Download Docker Desktop for windows [here](https://desktop.docker.com/win/main/amd64/Docker%20Desktop%20Installer.exe) or [visit the page](https://docs.docker.com/desktop/windows/install/) for more information.
@@ -64,7 +81,7 @@ cd FingerPrint
 cd fingerprint_service
 
 # build and start the service
-docker-compose up
+docker compose up -d --build
 ```
 
 ### Test the service
@@ -74,24 +91,17 @@ For windows users using xampp, that will be C:\xampp\htdocs or thereabouts.
 
 For linux users, that will be /var/www/html or thereabouts.
 
-Visit http://localhost/FingerPrint or http://localhost
+Visit http://localhost/FingerPrint/ or http://localhost/
 depending on your web root configuration. I do advice to change the web root directly to the FingerPrint directory.
 
+Before opening the application, check
+`http://localhost/FingerPrint/src/core/diagnostics.php` (adjust the base path if
+the project is your web root).
+
 Note: For this test we use a mysql database, but you can use any other database you want. You will need to have a database named `fingerprint`, with the below structure.
 
-```sql
-/*create fingerprint database*/
-CREATE DATABASE fingerprint;
-
-/*create users table, with id as primary key
-username, fullname columns and also nullable index and middle finger columns*/
-CREATE TABLE `users` (
-  `id` int(11) NOT NULL AUTO_INCREMENT,
-  `username` varchar(255) NOT NULL,
-  `fullname` varchar(255) NOT NULL,
-  `indexfinger` varchar(4000) NULL,
-  `middlefinger` varchar(4000) NULL,
-  PRIMARY KEY (`id`)
-) ENGINE=InnoDB DEFAULT CHARSET=latin1;
-``` 
+Import [`database/schema.sql`](database/schema.sql), copy
+`configs.local.php.example` to `configs.local.php`, and set the local database
+and fingerprint-service values. The local file is ignored by Git.
+
 Add some data and leave the index finger and middle finger columns empty. Now you should be able to enroll and verify fingerprints.

SECURITY.md

@@ -0,0 +1,26 @@
+# Security
+
+This repository is a proof of concept and must not be deployed as a production
+biometric identity system without a security review.
+
+## Reporting a vulnerability
+
+Open a GitHub security advisory for vulnerabilities. Do not post credentials,
+fingerprint samples, FMD templates, personal data, or exploitable details in a
+public issue.
+
+## Deployment baseline
+
+- Serve the browser application over HTTPS outside localhost.
+- Keep ports 4134 and 5555 on loopback or a private authenticated network.
+- Authenticate users and authorize enrollment and verification separately.
+- Add CSRF protection, request-size limits and rate limiting to PHP endpoints.
+- Encrypt biometric templates at rest with managed, rotated keys.
+- Never log request bodies containing FMD data.
+- Use a dedicated least-privileged MySQL account, not `root`.
+- Define retention, deletion, consent and audit policies appropriate to the
+  jurisdiction in which biometric data is processed.
+
+The provided Compose configuration binds service ports to `127.0.0.1` by
+default. Operators who deliberately expose them are responsible for adding TLS,
+authentication and network policy first.

configs.local.php.example

@@ -0,0 +1,10 @@
+<?php
+// Copy this file to configs.local.php. The copied file is ignored by Git.
+putenv('DB_HOST=127.0.0.1');
+putenv('DB_PORT=3306');
+putenv('DB_NAME=fingerprint');
+putenv('DB_USER=root');
+putenv('DB_PASSWORD=');
+putenv('FP_CLIENT_SERVICE_HOST=http://127.0.0.1:5555');
+putenv('FP_CLIENT_TIMEOUT=15');
+putenv('DIAGNOSTICS_ENABLED=1');

configs.php

@@ -1,7 +1,23 @@
 <?php
 /**
- * this should be the address of the fingerprint client
- * service
- * i.e the service for this repo: https://github.com/Ethic41/php-grpc-fingerprint-engine-client.git
+ * Application configuration.
+ *
+ * Values are read from the environment so the same code works with XAMPP,
+ * Docker and a hosted PHP installation. Defaults preserve the original local
+ * XAMPP behaviour.
  */
-putenv("FP_CLIENT_SERVICE_HOST=http://localhost:5555");
+
+if (!function_exists('fingerprint_config')) {
+    function fingerprint_config($name, $default = null)
+    {
+        $value = getenv($name);
+        return ($value === false || $value === '') ? $default : $value;
+    }
+}
+
+// XAMPP does not provide a convenient per-project environment file. A local,
+// ignored PHP file may set values with putenv(); see configs.local.php.example.
+$localConfig = __DIR__ . '/configs.local.php';
+if (is_file($localConfig)) {
+    require $localConfig;
+}

database/schema.sql

@@ -0,0 +1,15 @@
+CREATE DATABASE IF NOT EXISTS fingerprint
+    CHARACTER SET utf8mb4
+    COLLATE utf8mb4_unicode_ci;
+
+USE fingerprint;
+
+CREATE TABLE IF NOT EXISTS users (
+    id INT UNSIGNED NOT NULL AUTO_INCREMENT,
+    username VARCHAR(255) NOT NULL,
+    fullname VARCHAR(255) NOT NULL,
+    indexfinger TEXT NULL,
+    middlefinger TEXT NULL,
+    PRIMARY KEY (id),
+    UNIQUE KEY users_username_unique (username)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

docs/COMPATIBILITY.md

@@ -0,0 +1,75 @@
+# Compatibility and deployment models
+
+The application has three independent runtime layers:
+
+1. The DigitalPersona driver and Web SDK service run on the Windows computer connected to the reader.
+2. The PHP application stores users and Fingerprint Minutiae Data (FMD) in MySQL.
+3. The Linux fingerprint service performs enrollment and matching through the DigitalPersona engine.
+
+MySQL and PHP do not communicate with the USB reader directly.
+
+## Supported configurations
+
+| Profile | Browser and reader | PHP/MySQL | Fingerprint service | Status |
+| --- | --- | --- | --- | --- |
+| `xampp-local` | Windows 10/11 | XAMPP on the same PC | Docker Desktop on the same PC | Recommended for evaluation |
+| `hosted` | Windows 10/11 client | Remote PHP/MySQL server | Private service beside the PHP server | Recommended for deployment |
+| `local-docker` | Windows 10/11 | Existing local PHP/MySQL | Local Docker Desktop | Supported |
+| `shared-hosting` | Windows client | Shared PHP host | Separate HTTPS service | Conditional on outbound network access |
+| `xampp-no-docker` | Windows | XAMPP | Native Windows matching sidecar | Not implemented |
+
+## Important meaning of localhost
+
+`FP_CLIENT_SERVICE_HOST=http://127.0.0.1:5555` is correct only when PHP and the Docker service run on the same computer. In a hosted installation, `127.0.0.1` is the hosting server. It never refers to the Windows computer viewing the page.
+
+For hosted deployments, run the fingerprint service in the same private network as PHP and set `FP_CLIENT_SERVICE_HOST` to its private authenticated address. Do not expose the raw gRPC port to the Internet.
+
+## Windows baseline
+
+- 64-bit Windows 10 22H2 (build 19045) or a supported Windows 11 release.
+- WSL 2.1.5 or later, or a working Hyper-V configuration.
+- Hardware virtualization enabled in BIOS/UEFI.
+- Docker Desktop running Linux containers.
+- DigitalPersona U.are.U driver, SDK and Web SDK local service installed.
+- A supported browser able to communicate with the local Web SDK service.
+
+Windows Pro alone does not establish any of these prerequisites.
+
+## Local XAMPP setup
+
+1. Install the DigitalPersona driver/SDK and restart Windows.
+2. Install Docker Desktop and select Linux containers with the WSL 2 backend.
+3. Copy the repository to `C:\xampp\htdocs\FingerPrint`.
+4. Copy `configs.local.php.example` to `configs.local.php` and adjust values.
+5. Import `database/schema.sql` in phpMyAdmin or the MySQL CLI.
+6. From `fingerprint_service`, run `docker compose up -d --build`.
+7. Run `powershell -ExecutionPolicy Bypass -File scripts/windows-preflight.ps1`.
+8. Open `http://localhost/FingerPrint/src/core/diagnostics.php`.
+9. Open `http://localhost/FingerPrint/` and test reader enumeration before enrollment.
+
+## Hosted setup
+
+1. Install the reader driver and Web SDK on every Windows capture workstation.
+2. Serve the application over HTTPS.
+3. Configure database credentials through server environment variables.
+4. Deploy the fingerprint service beside the PHP server, not on the capture workstation.
+5. Configure `FP_CLIENT_SERVICE_HOST` with the service's private URL.
+6. Apply authentication, request-size limits, rate limits and TLS between services.
+7. Encrypt stored biometric templates and ensure application logs never contain FMD values.
+
+## Diagnostic endpoint
+
+`src/core/diagnostics.php` tests the PHP version, `mysqli`, database connection and TCP reachability of the configured fingerprint service. It deliberately does not return passwords, full connection strings or exception traces.
+
+Set `DIAGNOSTICS_ENABLED=0` after production commissioning if this endpoint is
+not protected by the application's administrator authorization.
+
+Browser capture remains a client-side check. Use the browser console and the Windows preflight script to distinguish missing JavaScript, a stopped DigitalPersona service and an undetected reader.
+
+## CPU architecture
+
+The bundled DigitalPersona Linux engine library is currently an `amd64`
+dependency. Compose declares `linux/amd64` explicitly so Windows x86-64 uses
+the correct image. ARM64 support requires an ARM64 build of the proprietary
+DigitalPersona engine library; emulation should not be presented as native
+support without scanner and matching tests.

docs/TROUBLESHOOTING.md

@@ -0,0 +1,45 @@
+# Troubleshooting
+
+Work from the reader toward the server. Do not post fingerprint samples, database passwords or tokens in an issue.
+
+## The reader list is empty
+
+1. Confirm the U.are.U reader appears in Windows Device Manager.
+2. Confirm the DigitalPersona driver and Web SDK runtime are installed and running.
+3. Unplug and reconnect the reader after the runtime starts.
+4. Open browser developer tools and check for `Fingerprint is not defined`, WebSocket errors or blocked mixed content.
+5. Run `scripts/windows-preflight.ps1` in PowerShell.
+
+## The page has no styling or buttons do nothing
+
+Update to the compatibility release. Older revisions used `/src/...` URLs, which break when the repository is installed at `/FingerPrint` under XAMPP.
+
+Check the browser Network panel for HTTP 404 responses.
+
+## Enrollment returns a service error
+
+From `fingerprint_service`, run:
+
+```powershell
+docker compose ps
+docker compose logs fingerprint_engine fingerprint_client
+Invoke-WebRequest http://127.0.0.1:5555/health.php
+```
+
+Then open `<application-url>/src/core/diagnostics.php`.
+
+## MySQL connection fails
+
+Confirm Apache and MySQL are running in XAMPP, import `database/schema.sql`, and configure `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER` and `DB_PASSWORD`. Do not use a passwordless root account outside a local development computer.
+
+## Information to include in a bug report
+
+- Output of `winver`.
+- Whether Docker Desktop uses WSL 2 or Hyper-V.
+- Output of `wsl --version`, `docker version`, and `docker compose ps`.
+- Redacted service logs.
+- XAMPP and PHP versions.
+- Exact application URL.
+- Browser name/version and redacted console errors.
+- Diagnostic endpoint output.
+- Whether Device Manager detects the reader.

fingerprint_service/.env.example

@@ -0,0 +1,7 @@
+# The proprietary DigitalPersona Linux libraries bundled by the engine are
+# currently built for x86-64.
+DOCKER_PLATFORM=linux/amd64
+FINGERPRINT_ENGINE_PORT=4134
+FINGERPRINT_CLIENT_PORT=5555
+FINGERPRINT_ENGINE_IMAGE=fingerprint-engine:local
+FINGERPRINT_CLIENT_IMAGE=fingerprint-client:local