MOSIP Reference Implementation

Overview

The MOSIP Reference Implementation (Ref Impl) repository contains country-specific customizations and implementations that extend the core MOSIP platform. It serves as a reference for how different countries can adapt and implement MOSIP according to their unique requirements and regulations.

Services

The mosip-ref-impl contains the following services:

1. cache-provider-hazelcast : Hazelcast based cache provider Reference implementation
2. cache-provider-redis : Redis based cache provider Reference implementation
3. kernel : Reference implementation for core libraries
   • kernel-ref-idobjectvalidator : Reference implementation for ID Object Validator
   • kernel-smsserviceprovider-msg91 : Reference implementation for msg91 SMS Service Provider
   • kernel-virusscanner-clamav : Reference implementation for clamv Virus Scanner
4. keycloak : Reference implementation for keycloak
5. pre-registration-booking-service : Reference implementation for pre-registration booking service.
6. registration-processor : Reference implementation for registration processor external integration.
   • registration-processor-external-integration-service : Reference implementation for external integration service.
   • registration-processor-external-stage : Reference implementation for external stage.

Local Setup

The project can be set up in two ways:

1. Local Setup (for Development or Contribution)
2. Local Setup with Docker (Easy Setup for Demos)

Prerequisites

Before you begin, ensure you have the following installed:

• JDK: 21.0.3
• Maven: 3.9.6
• Docker: Latest stable version
• PostgreSQL: 16.0
• Keycloak: Check here

Runtime Dependencies

Add the below dependencies to the classpath, or include it as a Maven dependency in your pom.xml.

• kernel-auth-adapter.jar
• kernel-ref-idobjectvalidator.jar

Configuration

• This module uses the following configuration files that are accessible in this mosip-config repository. Please refer to the required released tagged version for configuration:
  • Configuration-registration, Configuration-pre-registration and Configuration-Application are defined here. You need to run the config-server along with the files mentioned above.

Required Configuration Properties

The following properties must be configured with your environment-specific values before deployment:

Database Configuration:

• mosip.registration.processor.database.hostname - Database hostname (default: postgres-postgresql.postgres)
• mosip.registration.processor.database.port - Database port (default: 5432)
• db.dbuser.password - Database user password (passed as environment variable)

IAM/Keycloak Configuration:

• keycloak.internal.url - Internal Keycloak URL (passed as environment variable)
• keycloak.external.url - External Keycloak URL (passed as environment variable)
• mosip.regproc.client.secret - Registration processor client secret (passed as environment variable)

Service URLs:

• mosip.kernel.authmanager.url - Auth manager service URL
• mosip.kernel.keymanager.url - Key manager service URL
• mosip.kernel.masterdata.url - Masterdata service URL
• mosip.kernel.notification.url - Notification service URL
• mosip.idrepo.identity.url - ID repository identity service URL
• mosip.api.internal.url - Internal API base URL

Installation

Local Setup (for Development or Contribution)

1. Make sure the config server is running. For detailed instructions on setting up and running the config server, refer to the MOSIP Config Server Setup Guide.

Note: Refer to the MOSIP Config Server Setup Guide for setup, and ensure the properties mentioned above in the configuration section are taken care of. Replace the properties with your own configurations (e.g., DB credentials, IAM credentials, URL).

2. Clone the repository:

git clone <repo-url>
cd <service-name>

3. Build the project:

mvn clean install -Dmaven.javadoc.skip=true -Dgpg.skip=true

4. Start the application:

   • Click the Run button in your IDE, or
   • Run via command: java -jar target/specific-service:<$version>.jar

5. Verify Swagger is accessible.

Local Setup with Docker (Easy Setup for Demos)

Option 1: Pull from Docker Hub

Recommended for users who want a quick, ready-to-use setup — testers, students, and external users.

Pull the latest pre-built images from Docker Hub using the following commands:

docker pull mosipid/pre-registration-booking-service:1.3.0

Option 2: Build Docker Images Locally

Recommended for contributors or developers who want to modify or build the services from source.

1. Clone and build the project:

git clone <repo-url>
cd <service-name>
mvn clean install -Dmaven.javadoc.skip=true -Dgpg.skip=true

2. Navigate to each service directory and build the Docker image:

cd <service-name>/<service-directory>
docker build -t <service-name> .

Running the Services

Start each service using Docker:

docker run -d -p <port>:<port> --name <service-name> <service-name>

Verify Installation

Check that all containers are running:

docker ps

Access the services at http://localhost:<port> using the port mappings listed above.

Deployment

Kubernetes

To deploy mosip ref impl services on a Kubernetes cluster, refer to the Sandbox Deployment Guide.

Documentation

API Documentation

API endpoints, base URL, and mock server details are available via Stoplight and Swagger documentation for below services:

• Registration Processor External Integration Service API Documentation.
• Pre-Registration Booking Service API Documentation.

Product Documentation

For more detailed documents check below links:

• Registration Processor
• Pre-Registration
• keycloak
• Common components

Contribution & Community

• To learn how you can contribute code to this application, click here.

• If you have questions or encounter issues, visit the MOSIP Community for support.

• For any GitHub issues: Report here

License

This project is licensed under the Mozilla Public License 2.0.