Overview

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

The documentation here will guide you through the prerequisites required for the developer's setup.

Software setup

Below is 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. Install Apache Maven.

3. Copy the settings.xml to ".m2" folder C:\Users\<username>\.m2.

4. Install Eclipse.

5. Open the lombok.jar file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update. Specify the eclipse installation location if required by clicking the ‘Specify location…’ button. Then, click Install/Update the button to proceed.
6. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse to see if lombok.jar is added. By doing this, you will not have to add the dependency of lombok in your pom.xml file separately as it is auto-configured by Eclipse.

7. 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 a project

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

2. Open the 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 a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish.
5. After successful importing of the project, update the project by right-clicking on Project → Maven → Update Project.

Environment setup

1. For the environment setup, you need an external JAR that is available here with different versions. Download the below-mentioned JARs with appropriate latest/appropriate versions. You will need to input the appropriate artifact ID and version and other inputs.

   a. icu4j.jar

   b. kernel-auth-adapter.jar

   c. kernel-ref-idobjectvalidator.jar

   d. kernel-transliteration-icu4j.jar

   E.g.: You can download kernel-auth-adapter.jar and add to the project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close).
2. Clone mosip-config repository.

   a. As Resident Services is using two properties files- resident-default.properties and application-default.properties. But for the local running of the application, you need to provide additional/overriding properties such as secrets, passwords, and properties passed by the environment which can be added to new files application-dev-default.properties (common properties for all modules) and resident-dev-default.properties (Resident service-specific properties).

   b. You will have to create both the property files according to your environment and put them in mosip-config folder (cloned). The same files are available below for reference.

   These two files are loaded by the application by specifying the application names in the Application VM arguments like- Dspring.cloud.config.name=application,resident,application-dev, resident-dev (also detailed in a later section).

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

4. Put both files in the same folder and point to the property- Dspring.cloud.config.server.native.search-locations to mosip-config folder in config-server-start.bat file and also check the version of kernel-config-server.jar towards the end of the command.

   Example:

   Copy

   java -jar -Dspring.profiles.active=native  -
   Dspring.cloud.config.server.native.search-
   locations=file:C:\Users\myDell\mosipProject\mosip-config -
   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 earlier, you will have to create property files according to your environment like resident-env-default and application-env-default (here env represents environment name). Both files will contain different configurations such as resident-env-default will have config properties (e.g., secrets, passcodes, etc) used for the resident-services module only and application-env-default is used for environment-specific changes and can be used for other modules as well.

• In this example, currently, these two files are created for the dev environment and hence the files have suffixes of -dev. If you want to run it for a different environment such as qa, create these two files with -qa suffixes, and then you will also need to provide the appropriate VM argument for that referring to qa environment.

For instance,

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

• If you check the URLs present in application-default the file, they are set to module-specific URLs, but you need to use internal/external environment URLs to access the APIs by using an application-dev-default file.

• In application-dev-default file, assign environment domain URL to mosipbox.public.url , and change all other URLs with ${mosipbox.public.url}.

• It results in mosipbox.public.url=internal/externalAPI (e.g., mosipbox.public.url=https://api-internal.dev.mosip.net) and it will connect with the Development environment.

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

Configurations to be done in Eclipse

1. Open Eclipse and run the project for one time as a 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 the environment - "Resident-dev").
2. Open the Arguments tab and specify Application VM arguments: For example, for a development environment:

   Copy

   -Dspring.profiles.active=default -
    Dspring.cloud.config.uri=http://localhost:51000/config -
    Dspring.cloud.config.label=master -Dsubdomain=dev -
    Dspring.cloud.config.name=application,resident,application-dev,resident-dev --illegal-access=permit.

   Save this run configuration as ‘Resident-dev’ .

   For qa environment, you can create Resident-qa run configuration with VM argument as below.

   Example:

   Copy

   -Dspring.profiles.active=default -
   Dspring.cloud.config.uri=http://localhost:51000/config -
   Dspring.cloud.config.label=master -Dsubdomain=qa -
   Dspring.cloud.config.name=application,resident,application-qa,resident-qa --illegal-access=permit
3. 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 Postman or Swagger-UI.

• 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 a widely used tool for API testing. Below you will find the APIs postman collection of resident-services.

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

• Download the JSON collection available below and import it to your postman. Resident-Service-APIs.postman_collection-latest.json.

• Create an environment as shown in the image below.

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

• Similarly, create another environment as shown below.

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

This repository contains the UI code for the Resident portal. To know more about the features and functions present on the portal, refer here.

Build and Deployment

• Install node.js- To build the angular code using angular cli that runs on node, recommended Node: 14.17.3, Package Manager: npm 6.14.13

• Install angular cli – To install angular cli for building the code into deployable artifacts. Follow the following steps to install angular cli on your system.

  • npm install -g @angular/cli (to install angular cli)

  • ng --version (to verify angular is installed in the system) We recommend Angular CLI: 7.2.1

• Check out the source code from GIT – To download the source code from git, follow the steps below to download the source code on your local system.

  • git clone https://github.com/mosip/resident-ui.git (to clone the source code repository from git)

For Production build

• Build the code

  Follow the steps below to build the source code on your system.

  • Navigate to the resident-ui directory inside the cloned repository.

  • Run the command ng build "--prod" "--base-href" "." "--output-path=dist" in that directory to build the code.

• Build Docker image

  Follow the steps below to build the docker image on your system.

  • docker build -t name . (replace name with the name of the image you want, "." signifies the current directory from where the docker file has to be read.)

  • Example: docker build -t residentui .

• Run the Docker image

  Follow the steps to build a docker image on your system.

  • docker run –d –p 80:80 --name container-name image-name (to run the docker image created with the previous step,-d signifies to run the container in detached mode, -p signifies the port mapping left side of the":" is the external port that will be exposed to the outside world and the right side is the internal port of the container that is mapped with the external port. Replace container-name with the name of your choice for the container, replace image-name with the name of the image specified in the previous step)

  • Example: docker run -d -p 8080:8080 --name nginx residentui

• Now you can access the user interface over the internet via a browser.

  • Example: http://localhost:8080/#/dashboard

For Local build

• Build & deploy the code locally

  Follow the steps below to build the source code on your system.

  • Navigate to the resident-ui directory inside the cloned repository. Then, run the following command in that directory:

    • npm install

    • ng serve

• Now, you can access the user interface via the browser.

  • Example: http://localhost:4200

UI & Rest end points:

The table below outlines the frameworks, tools, and technologies employed by Resident Portal.

Resident Services:

The table below outlines the frameworks, tools, and technologies employed by Resident Services.

Overview

UI specs of resident module are used to configure the form fields across Resident Portal. UI specs are saved as a JSON file with a list of fields. Each field has a set of attributes/ properties that can be configured which affects the look and feel along with the functionality of the field.

Below is the list of all the properties available for each field in the Resident Portal UI specs: