Mosip sandbox deployment handover

# Turing MOSIP V3 Sandbox Deployment ## Contents - **Introduction** - **Using this document** - **Infrastructure overview** - **Accounts and credentials** - **Current state (progress to date)** - **Next steps** - **Troubleshooting** ## Introduction This document was prepared by REG team members on the [Trustworthy Digital Identity project](https://www.turing.ac.uk/research/research-projects/trustworthy-digital-infrastructure-identity-systems) in December 2023 as part of the handover documentation to support future use of the Turing's MOSIP Sandbox installation. It summarises the (lengthy) deployment process of the MOSIP V3 system on AWS, complementing the official MOSIP documentation with details specific to the Turing's MOSIP instance. It also describes the state of the V3 installation, as of December 2023, and sets out the next steps towards demonstrating the full user registration and authentication workflow. Finally, some troubleshooting hints are provided to help overcome the most common problems encountered during the deployment phase. :::info Note: Instructions for accessing the MOSIP V3 Sandbox components can be found in a separate document by following [this link](https://hackmd.io/KYz5edygQs28AHbBszl79A?view). ::: ## Using this document **Aims:** - Provide a high level overview of the MOSIP system with targeted links to the MOSIP docs. - Provide hand-over information for new developers/researchers to continue existing work. - Bring together links to more detailed resources and records. :::warning Warning: **Links to MOSIP documentation may have become outdated** because the software (and docs website) is under constant development. In the event of a broken link, visit the [homepage](https://docs.mosip.io/) and try to navigate towards the required information. ::: ## Infrastructure overview This MOSIP installation is comprised of **a set of clients** which are used by end-users (ranging from system admins, through "registration officers", to members of the public registering on the system), and **a backend system** deployed in the AWS cloud. ### The clients: - **[Pre-registration Client](https://docs.mosip.io/1.2.0/modules/pre-registration/pre-registration-user-guide)**: A web-application. - **[Registration Client](https://docs.mosip.io/1.2.0/modules/registration-client/registration-client-user-guide)**: A program/application installed on one of the "rugged" windows laptops. - **[Authentication Client](https://github.com/mosip/authentication-demo-ui/tree/release-1.2.0)**: A program/application installed on one of the "rugged" windows laptops. - **[Admin Portal](https://docs.mosip.io/1.2.0/modules/administration/admin-portal-user-guide)**: A web-application. - **[Rancher Dashboard](https://rancher.turing-mosip.net/dashboard/)**: A web-application used to monitour, configure and edit the kubernetes clusters deployed in the AWS cloud. - **[Keycloak Dashboard](https://iam.sandbox.turing-mosip.net/auth/)**: A web-application for managing IAM (Identity Access Management) configurations. :::info Note: There are further web-based dashboards/portals, which have not been used or tested to date - futher information is available in main [installation docs](https://docs.mosip.io/1.2.0/deploymentnew/v3-installation/aws-installation-guidelines-new) ::: ### The backend system: There are several deployment options for the backend system, discussed [here](https://docs.mosip.io/1.2.0/deploymentnew). The following applies to the infrastructure used for this installation: **V3 AWS Native Deployment**. The associated [documentation](https://docs.mosip.io/1.2.0/deploymentnew/v3-installation/aws-installation-guidelines-new) was used as the main resource throughout the backend installation. The following components make up the backend system: - **2 Kubernetes clusters** AWS EKS (Elastic Kubernetes Service) resources: - **The observation cluster:** - 2 nodes (virtual machines). - The cluster name in AWS is `rancher`. - Used for monitoring. - **The MOSIP cluster:** - 4 nodes. - The cluster name in AWS is `v3box1`. - Provides the main compute. - **An EC2 machine used as a VPN:** - A standalone AWS virtual machine, with **Wireguard** vpn software installed. - This machine is in the same **VPC (virtual private cloud)** as the two kubernetes clusters, so it is able to act as a secure gateway into the private cloud. - New researchers/system users can download **Wireguard** client software on their personal machines, obtain a vpn configuration file, and then access the backend endpoints **all of which are *not* exposed to public IP addresses**. - **The *turing-mosip.net* domain and associated DNS records:** - Records are managed with AWS Route53. - Records can optionally point to either **the internal/private endpoints** of the backend, or **publically accessable endpoints**. - The internal channel, `api-internal` is currently configured **for all records**. :::info An active VPN connection to the wiregurad vpn is required to access **any** of the resources, portals, clients or dashboards. ::: ## Accounts and credentials :::success This section is maintained separately for security. See the associated **`accounts_and_credentials.md`** file on the (private) [project repository](https://github.com/alan-turing-institute/trustworthy-id/tree/master/MOSIP/V3_Sandbox). ::: :::info The MOSIP V3 sandbox is deployed on the TDI project's AWS subscription at: https://the-alan-turing-institute.awsapps.com/start#/. ::: ## Current state (progress to date) :::info Note: Instructions for accessing the MOSIP V3 Sandbox components can be found in a separate document by following [this link](https://hackmd.io/KYz5edygQs28AHbBszl79A?view). ::: - **Wireguard VPN**: - To give new users VPN access follow the steps that must be taken by a system admin/developer detailed in the **`accounts_and_credentials.md`** file. - The steps to be taken by the end user/research user are detailed in this [user guide](https://hackmd.io/KYz5edygQs28AHbBszl79A?view). - **Rancher Dashboard**: Accessible [here](https://rancher.turing-mosip.net/dashboard/). - Log in credentials above. - Useful for checking the logs of pods in the aws clusters. - **Keycloak Dashboard** Accessible [here](https://iam.sandbox.turing-mosip.net/auth/). - Log in to the [keycloak administration console](https://iam.sandbox.turing-mosip.net/auth/admin/master/console) (accessed by the link or by navigating to it from the main keycloak dashboard) required authentication with the **admin** user (details in the **Accounts and credentials** section). The **globaladmin** user is to be used to access other backend resources, and does not have elevated permissions to make changes to the IAM condifuration (eg. adding new roles etc.) - **Admin Console**: Accessible following steps [here](https://hackmd.io/KYz5edygQs28AHbBszl79A?view). Where passwords are referenced, find them in the table above. - **Pre-registration client**: Accessible [here](https://prereg.sandbox.turing-mosip.net/pre-registration-ui/) but not fully tested. - Starting a pre-registration session has been successfully tested (Note: the OTP is always `111111`). - Completing a pre-registration session has _not_ been tested (eg. entering information and submitting). - **Registration Client**: Accessible but not fully tested. - The registration client has been installed on one of the project's rugged DELL laptops, identifiable by a sticker on the back which reads "REG CLIENT". - The logs have been inspected to ensure that the machine successfully connects to the backend system - this also results in a "MACHINE IS ONLINE" message shown while the client loads. - Logging into the client with registration operator credentials has _not_ yet been tested. - **Authentication Client**: Accessible but not fully tested. - The registration client has been installed on one of the project's rugged DELL laptops, identifiable by a sticker on the back which reads "AUTH CLIENT". - Progress to date is documented [here](https://hackmd.io/rctkpROVTiCZJvrk7B9NXQ). :::info **Notes were taken throughout the V3 MOSIP installation process, accessible [here](https://hackmd.io/5_zt5mGUSPeXNgeS8tG8Yg?both)**. - The notes contain a commentary on carrying out the steps in the MOSIP docs for a [V3 AWS Native Installation](https://docs.mosip.io/1.2.0/deploymentnew/v3-installation/aws-installation-guidelines-new) (the main documentation resource, and linked several times throughout this document). - The notes **may** be of use to future developers, but are verbose and in most cases it would be better to refer to the associated MOSIP docs. - The notes also contain brief summaries of the bug fixes found during a series of meetings with the MOSIP engineering team. ::: ## Next steps - Test a pre-registration to completion. - Onboard a registration "operator" (used to log into the registration client), docs [here](https://docs.mosip.io/1.2.0/modules/registration-client/operator-onboarding). - Test a registration to completion, with dummy biometric data injected using MOSIP's [mock-data services](https://github.com/mosip/mosip-mock-services). :::info Note: guidance for populating the MOSIP database by simulating MOSIP pre-registration & registration sessions, including the use of Mock Data Services, can be found in the REG [Working with MOSIP Handbook](https://github.com/alan-turing-institute/trustworthy-id-handbook/wiki/Handbook). ::: ## Troubleshooting ### 1. Network connection problems when accessing any clients/resources hosted by the backend system. - By far the most common problem. - Most likely due to a **misconfigured VPN**. - Deactivate all other VPN connections (eg. Turing VPN, University VPN etc..) - Activate the wireguard VPN connection (see info in this guide). - Try visiting serveral backend urls (eg. https://sandbox.turing-mosip.net/, https://prereg.sandbox.turing-mosip.net/pre-registration-ui/, https://rancher.turing-mosip.net/dashboard/). - If access to any is successful, then the VPN connection is **not** the problem. - **Some wifi networks will block access to the vpn (eg. wifi onsite at the Turing, some personal wifi networks in the home). To rule this out, connect the personal machine to a personal hotspot on a mobile phone that is using mobile data.** ### 2. Errors thrown whilst using clients (eg. "server error"). - For web clients: Reason about, or check the details of the failed requests in the browser to identify the pod(s)/ MOSIP module that is likley to be responsible. - eg. Problems with prereg -> prereg-application pod - For installed clients: Check log files. - Then check the logs of suspect pods from within the [Rancher Dashboard](https://rancher.turing-mosip.net/dashboard/auth/login).