Skip to content

[MOSIP-44051]: Updated Readme #200

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Prafulrakhade merged 2 commits into from
Dec 19, 2025
Merged

[MOSIP-44051]: Updated Readme #200

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0be5f93
[MOSIP-44051]: Updated Readme
chetankh239 Dec 16, 2025
cfeecce
[MOSIP-44051]: Updated Readme
chetankh239 Dec 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 15 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,22 @@
[![Maven Package upon a push](https://github.com/mosip/biosdk-services/actions/workflows/push-trigger.yml/badge.svg?branch=release-1.3.x)](https://github.com/mosip/biosdk-services/actions/workflows/push-trigger.yml)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?branch=release-1.3.x&project=mosip_biosdk-services&metric=alert_status)](https://sonarcloud.io/dashboard?branch=release-1.3.x&id=mosip_biosdk-services)

# Bio-SDK Service
[![Maven Package upon a push](https://github.com/mosip/biosdk-services/actions/workflows/push-trigger.yml/badge.svg?branch=release-1.3.x)](https://github.com/mosip/biosdk-services/actions/workflows/push-trigger.yml)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?branch=release-1.3.x&project=mosip_biosdk-services&id=mosip_biosdk-services&metric=alert_status)](https://sonarcloud.io/dashboard?branch=release-1.3.x&id=mosip_biosdk-services)

## Overview
This is reference service and provides a mock implementation of Bio-SDK REST Service. By default loads [Mock BIO SDK](https://github.com/mosip/mosip-mock-services/tree/master/mock-sdk) internally on the startup and exposes the endpoints to perform 1:1 match, extraction as per the [IBioAPIV2](https://github.com/mosip/commons/blob/master/kernel/kernel-biometrics-api/src/main/java/io/mosip/kernel/biometrics/spi/IBioApiV2.java).
This is reference service and provides a mock implementation of Bio-SDK REST Service. By default loads [Mock BIO SDK](https://github.com/mosip/mosip-mock-services/tree/master/mock-sdk) internally on the startup and exposes the endpoints to perform 1:1 match, extraction as per the [IBioAPIV2](https://github.com/mosip/bio-utils/blob/master/kernel-biometrics-api/src/main/java/io/mosip/kernel/biometrics/spi/IBioApiV2.java).

To know more about Biometric SDK, refer [biometric-sdk](https://docs.mosip.io/1.2.0/biometrics/biometric-sdk).

To know more about implementation, [refer here](biosdk-services/README.md).

## Contribution & Community

• To learn how you can contribute code to this application, [click here](https://docs.mosip.io/1.2.0/community/code-contributions).

• If you have questions or encounter issues, visit the [MOSIP Community](https://community.mosip.io/) for support.

• For any GitHub issues: [Report here](https://github.com/mosip/biosdk-services/issues)


### License
This project is licensed under the terms of [Mozilla Public License 2.0](LICENSE).
This project is licensed under the terms of [Mozilla Public License 2.0](LICENSE).
194 changes: 162 additions & 32 deletions biosdk-services/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,73 +1,203 @@
# Bio SDK services

This service provides a mock implementation of Bio-SDK REST Service. It by default loads [Mock BIO SDK](https://github.com/mosip/mosip-mock-services/tree/master/mock-sdk) internally on the startup and exposes the endpoints to perform 1:N match, segmentation, extraction as per the [IBioAPI](https://github.com/mosip/commons/blob/master/kernel/kernel-biometrics-api/src/main/java/io/mosip/kernel/biometrics/spi/IBioApiV2.java). This can be configured to load a different JAR that has a different implementation of `IBioAPIV2`, provided its dependencies are in place.
## Overview

## Requirements:
* Java version = 21.X.X
* Maven version >= 3.9.6
This service offers a mock implementation of the Bio-SDK REST Service. By default, it initializes the [Mock BIO SDK](https://github.com/mosip/mosip-mock-services/tree/master/mock-sdk) during startup and exposes endpoints for performing 1:N matching, segmentation, and extraction, adhering to the [IBioAPIV2](https://github.com/mosip/bio-utils/blob/master/kernel-biometrics-api/src/main/java/io/mosip/kernel/biometrics/spi/IBioApiV2.java) specification.

## Run jar directly
Additionally, the service is configurable to load an alternative JAR implementing `IBioAPIV2`, provided all necessary dependencies are satisfied. This flexibility allows users to integrate customized implementations seamlessly.

### Build
## Table of Contents

- [Prerequisites](#prerequisites)
- [Setting Up Locally](#setting-up-locally)
- [Running the Application](#running-the-application)
- [Configurations](#configurations)
- [APIs Provided](#apis-provided)
- [API Documentation](#api-documentation)
- [License](#license)

## Prerequisites

Ensure you have the following installed before proceeding:

1. **Java**: Version 21.0.3
2. **Maven**: For building the project 3.9.6
3. **Git**: To clone the repository
4. **Postman (optional)**: For testing the APIs

---

## Setting Up Locally

### Follow these steps to set up the project on your local environment:

1. **Clone the repository**

Clone the repository from GitHub to your local machine:

Go to biosdk-services folder and run the below command, this will create a jar file in target folder
```text
mvn clean install
git clone https://github.com/mosip/biosdk-services.git
cd biosdk-services
```

### Run jar
2. **Build the project**

Use Maven to build the project and resolve dependencies.

```text
java -Dloader.path=<biosdk jar provided by third-party vendors> -Dbiosdk_bioapi_impl=<classpath of class that implements IBioApi interface> --add-modules=ALL-SYSTEM --add-opens java.xml/jdk.xml.internal=ALL-UNNAMED --add-opens java.base/java.lang.reflect=ALL-UNNAMED --add-opens java.base/java.lang.stream=ALL-UNNAMED --add-opens java.base/java.time=ALL-UNNAMED --add-opens java.base/java.time.LocalDate=ALL-UNNAMED --add-opens java.base/java.time.LocalDateTime=ALL-UNNAMED --add-opens java.base/java.time.LocalDateTime.date=ALL-UNNAMED -jar biosdk-services-<version>.jar
mvn clean install -Dgpg.skip=true
```


3. **Start the application**

Run the application using the following command:

```java
java -Dloader.path=<biosdk jar provided by third-party vendors> -Dbiosdk_bioapi_impl=<classpath of class that implements IBioApiV2 interface> --add-modules=ALL-SYSTEM --add-opens java.xml/jdk.xml.internal=ALL-UNNAMED --add-opens java.base/java.lang.reflect=ALL-UNNAMED --add-opens java.base/java.lang.stream=ALL-UNNAMED --add-opens java.base/java.time=ALL-UNNAMED --add-opens java.base/java.time.LocalDate=ALL-UNNAMED --add-opens java.base/java.time.LocalDateTime=ALL-UNNAMED --add-opens java.base/java.time.LocalDateTime.date=ALL-UNNAMED -jar biosdk-services-<version>.jar
```

For example:
```text
java -Dloader.path=mock-sdk-1.2.1-SNAPSHOT-jar-with-dependencies.jar -Dbiosdk_bioapi_impl=io.mosip.mock.sdk.impl.SampleSDKV2 -jar biosdk-services-1.2.1-SNAPSHOT.jar

```java
java -Dloader.path=mock-sdk-1.3.0-jar-with-dependencies.jar -Dbiosdk_bioapi_impl=io.mosip.mock.sdk.impl.SampleSDKV2 --add-modules=ALL-SYSTEM --add-opens java.xml/jdk.xml.internal=ALL-UNNAMED --add-opens java.base/java.lang.reflect=ALL-UNNAMED --add-opens java.base/java.lang.stream=ALL-UNNAMED --add-opens java.base/java.time=ALL-UNNAMED --add-opens java.base/java.time.LocalDate=ALL-UNNAMED --add-opens java.base/java.time.LocalDateTime=ALL-UNNAMED --add-opens java.base/java.time.LocalDateTime.date=ALL-UNNAMED -jar biosdk-services-1.3.0.jar
```

### Check service status
4. **Verify the setup**

Once the application is running, confirm that it is operational by accessing the health check endpoint:

For your host:

```text
http://{host}:9099/biosdk-service
http://{host}:9099/biosdk-service
```

In case of localhost:
http://localhost:9099/biosdk-service
```
You will see response like

```text
Service is running... Fri Jan 29 08:49:28 UTC 2021
http://localhost:9099/biosdk-service
```

You will see the below response:

```text
Service is running... Fri Jan 29 08:49:28 UTC 2021
```
---


## Run as docker
## Running the Application

### Build docker image
### Using Docker (Optional)

Build the Dockerfile to create docker image
You can run the application with Docker for easier deployment and environment isolation.

### Run docker image
1. **Build the Docker image**

Run the docker image by providing:
* biosdk_zip_url (environment variable), url for third-party biosdk library zip file
* biosdk_bioapi_impl (environment variable) where biosdk_zip_url is the path of the class that implements IBioApi interface methods
Before building the image, set the following environment variables:

* biosdk_zip_url - The URL pointing to the third-party BioSDK library ZIP file.
* biosdk_bioapi_impl - The fully qualified class name implementing the IBioApiV2 interface.

Run the below command to build the Docker image:

### Check service status
```text
http://{host}:9099/biosdk-service
docker build -t mosip/biosdk-services .
```

In case of localhost:
http://localhost:9099/biosdk-service
2. **Run the Docker container**

Run the below command:

```text
docker run -d -p 8080:8080 mosip/biosdk-services
```
You will see response like

3. **Verify the container**

Ensure the application is running correctly by following these steps:

* **Check running containers:**

Use the docker ps command to verify that the container is up and running:

```text
Service is running... Fri Jan 29 08:49:28 UTC 2021
docker ps
```
* **Test the health endpoint:**

Use curl to check the application's health:

```text
curl http://localhost:9099/health
```

## Swagger UI for exposed APIs
* **Expected Response:**

If the setup is successful, you will see a response similar to below:

```text
Service is running... Fri Jan 29 08:49:28 UTC 2021
```
---

## Configurations
BioSdk Service uses the following configuration files that are accessible in this [repository](https://github.com/mosip/mosip-config/tree/master).
Please refer to the required released tagged version for configuration.
1. [Configuration-Application](https://github.com/mosip/mosip-config/blob/master/application-default.properties)
2. [Configuration-Biosdk-Service](https://github.com/mosip/mosip-config/blob/master/biosdk-service-default.properties)

Need to run the config-server along with the files mentioned above in order to run the BioSdk service.

---

## APIs Provided

BioSDK-Services provides the following key endpoints:

| Endpoint | Method | Description |
|-------------------------|--------|---------------------------------|
| `/biosdk-service/init` | POST | Can be used to init the SDK |
| `/biosdk-service/match` | POST | Validates biometric matching with probe and gallery |
| `/biosdk-service/segment` | POST | Segmentation of biometric records |
| `/biosdk-service/extract-template` | POST | Extract the template for the given biometric record |
| `/biosdk-service/convert-format` | POST | Convert biometric record ISO to JPEG/PNG using [here](https://github.com/mosip/converters/tree/release-1.3.x). |
| `/biosdk-service/check-quality` | POST | Check the quality for the a given biometric record |


## Documentation

Please refer to the [Documentation](https://github.com/mosip/documentation/blob/1.2.0/docs/biometric-sdk.md) to know more about Bio SDK

---

## API Documentation

Swagger UI to explore the exposed APIs:

For your host:

```text
http://{host}:9099/biosdk-service/swagger-ui.html
```

In case of localhost:

```
http://localhost:9099/biosdk-service/swagger-ui.html
```
---
## Contribution & Community

• To learn how you can contribute code to this application, [click here](https://docs.mosip.io/1.2.0/community/code-contributions).

• If you have questions or encounter issues, visit the [MOSIP Community](https://community.mosip.io/) for support.

• For any GitHub issues: [Report here](https://github.com/mosip/biosdk-services/issues)

## License

This project is licensed under the terms of [Mozilla Public License 2.0](https://github.com/mosip/admin-services/blob/release-1.3.x/LICENSE).

---