Resident Services Developers Guide

Overview

Resident Services are the self-services which are used by the residents themselves via a portal. Resident Portal is a web based UI application that provides residents of a country the services related to their Unique Identification Number (UIN).

The documentation here will guide you through the pre-requisites required for the developer' setup.

Software setup

Below are a list of tools required in Resident Services:

  1. JDK 11

  2. Any IDE (like Eclipse, IntelliJ IDEA)

  3. Apache Maven (zip folder)

  4. pgAdmin

  5. Postman

  6. Git

  7. Notepad++ (optional)

  8. lombok.jar (file)

  9. settings.xml (document)

Follow the steps below to set up Resident Services on your local system:

  1. Download lombok.jar and settings.xml from here.

  2. Unzip Apache Maven and move the unzipped folder in C:\Program Files and settings.xml to "conf" folder C:\Program Files\apache-maven-3.8.4\conf.

  3. Install Eclipse, open the lombok.jar file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update.

  1. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse to see if the lombok.jar is added. By doing this, you don't have to add the dependency of lombok in your pom.xml file separately as it is auto-configured by Eclipse.

  2. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs.

Code setup

For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.

Importing and building of a project

  1. Open the project folder where pom.xml is present.

  2. Open command prompt from the same folder.

  3. Run the command mvn clean install -Dgpg.skip=true -DskipTests=true to build the project and wait for the build to complete successfully.

  4. After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish.

  5. After successful importing of project, update the project by right-click on Project → Maven → Update Project.

Environment setup

  1. For the environment setup, you need an external JAR that is available here with different versions. (E.g.: You can download kernel-auth-adapter.jar and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close).

  1. Clone mosip-config repository.

  2. Create an empty folder inside the mosip-config with sandbox-local name and then copy and paste all config files inside sandbox-local folder except .gitignore, README and LICENSE.

  3. As Resident Services is using two properties files, resident-default and application-default, you will have to configure them according to your environment. The same files are available here for reference.

  4. To run the server, two files are required- kernel-config-server.jar and config-server-start.bat.

  5. Put both the files in the same folder and change the location attribute to sandbox-local folder in config-server-start.bat file and also check the version of kernel-config-server.jar towards the end of the command.

Example:

java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:C:\Users\myDell\mosipProject\mosip-config\sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar.

As mentioned in step 4, you may have to make some changes in the two properties files.

For instance,

  • Add mosip.mosip.resident.client.secret=xyz789 property to be able to use a decrypted passcode and run it in your local machine.

  • If you are running it on a server, then you have to use an encrypted passcode like this mosip.mosip.resident.client.secret={cipher}1bdd7e59ca3a9dbe66b47db3ecb7025e66a6746911de2bd841c804f.

  • Comment this out auth.server.admin.issuer.internal.uri in application-default file because you already have this auth.server.admin.issuer.uri , and hence there is no need of auth.server.admin.issuer.internal.uri.

  • If you check the URLs present in these files, they are set to default with port no. 80 (or any other port number) but you need to use external URL to access it.

  • In the beginning of resident-default file, add mosipbox.public.url=https://${domain.url} and change all other URLs with ${mosipbox.public.url}.

  • This is because you will pass this domain URL in Eclipse VM arguments like this -Ddomain.url=dev.mosip.net which results in mosipbox.public.url=https://dev.mosip.net and it will connect with the Development environment.

  1. Run the server by opening the config-server-start.bat file.

The server should now be up and running.

Below are the configurations to be done in Eclipse:

  1. Open Eclipse and run the project for one time as Java application, so that it will create a Java application which you can see in debug configurations and then change its name. (e.g.: project name with environment - "Resident-dev").

  1. Open the arguments and pass this -Ddomain.url=dev.mosip.net -Dapplication.base.url=http://localhost:8090 -Dspring.profiles.active=default -Dspring.cloud.config.uri=http://localhost:51000/config -Dspring.cloud.config.label=master in VM arguments.

  2. Here, the domain URL represents the environment on which you are working (eg., it can be dev2.mosip.net or qa3.mosip.net).

  1. Click Apply and then debug it (starts running). In the console, you can see a message like "Started ResidentBootApplication in 34.078 seconds (JVM running for 38.361)".

Resident services API

  • For API documentation, refer here.

  • The APIs can be tested with the help of Swagger-UI and Postman.

  • Swagger is an interface description language for describing restful APIs expressed using JSON. You can access Swagger-UI of resident-services for dev-environment from https://dev.mosip.net/resident/v1/swagger-ui/index.html?configUrl=/resident/v1/v3/api-docs/swagger-config and localhost from http://localhost:8099/resident/v1/swagger-ui/index.html?configUrl=/resident/v1/v3/api-docs/swagger-config.

  • Postman is an API platform for building and using APIs. Postman simplifies each step of the API lifecycle and streamlines collaboration so you can create better APIs—faster. It is widely used tool for API testing. Below you will find the APIs postman collection of resident-services.

  • Download the JSON collection and then import it in your postman.

  • Create an environment as shown in the image below.

This environment is created for dev. Give the variable name as url and set both the values as https://dev.mosip.net.

  • In the similar way, create another environment as shown below.

This environment is created for localhost. Give the variable name as url and set both the values as http://localhost:8099.

PreviousResident ServicesNextResident Mobile Application (Draft)

Last updated