Update Documentation For Cat-Server

[Gokul-KG]

Documentation for Cat-Server

Link to reference ACL-APD design document for reference: https://docs.google.com/document/d/1j289zdt2n5i81vvwJJl-lJB-D4Ld8ihQajjN3qZuGM8/edit

• logo to be added in docs and referenced in all documentation-related markdown files

  • reference to the logo to be added in docs: https://github.com/datakaveri/dx-acl-apd/blob/main/docs/cdpg.png

• all the diagrams could be added in /docs folder

• Change the references from IUDX to DX, CDPG

• video tutorial could be added optionally

• README.md - Introduction

  • updated overview diagram: https://drive.google.com/file/d/1x2e_XP6U9K1Nl7EGjv7dxJ08HGp1vhaC/view
  • Features
  • Explanation

    • Understanding DMP APD

    • Reference Solution_Architecture.md, postman collection, env file

    • How to guide

      • Setup and Installation
        • Reference Setup_and_Installation.md

    • Tutorial

      • Tutorials and Explanation (optional)
  • Reference:
    • API Docs: Reference Redocly URL of the openapi specs
    • FAQ: Reference FAQ.md

• CONTRIBUTING.md

  • Git Merge workflow
  • Code style
    • tutorial to install plugins could be added optionally
  • Commit message section

• LICENSE.md

  • No change required

• CODE_OF_CONDUCT.md

  • Contributor code of Conduct
  • Our pledge
  • Our standards
  • Attribution
  • Reference: https://github.com/datakaveri/dx-acl-apd/blob/main/CODE_OF_CONDUCT.md

• SECURITY.md * yet to be added in ACL-APD

  • overview
  • how to report security issues in an encrypted format
  • email address to mail to
  • acknowledgements if any
    *inspirations: https://blogs.eclipse.org/post/marta-rybczynska/securitymd-should-i-have-it, https://github.com/microsoft/.github/blob/main/SECURITY.md

• docs/Configurations.md

  • Modules (verticle and other configs)
    • Api Server Verticle

Key Name	Value Datatype	Value Example	Description
isWorkerVerticle	boolean	false	To check if worker verticle needs to be deployed for blocking operations
verticleInstances	integer	1	Number of instances required for verticles
httpPort	integer	8080	Port for running the instance DX ACL-APD Server

	- Other Configurations
		* include common configs and other configurations

Key Name	Value Datatype	Value Example	Description
version	Float	1.0	config version
zookeepers	Array	zookeeper	zookeeper configuration to deploy clustered vert.x instance
clusterId	String	iudx-acl-apd-cluster	cluster id to deploy clustered vert.x instance
commonConfig.dxApiBasePath	String	/dx/apd/acl/v1	API base path for DX ACL-APD. Reference : link
commonConfig.dxCatalogueBasePath	String	/iudx/cat/v1	API base path for DX Catalogue server. Reference : link
commonConfig.dxAuthBasePath	String	/auth/v1	API base path for DX AAA server. Reference : link
commonConfig.catServerHost	String	api.cat-test.iudx.io	Host name of DX Catalogue server for fetching the information of resources, resource groups
commonConfig.catServerPort	integer	443	Port number to access HTTPS APIs of Catalogue Server
commonConfig.authHost	String	authvertx.iudx.io	Host name of DX AAA Server

* it would help us to see if there any unused configurations that could be removed from config.json

• Explanation.md

  • Tokens used in DX in a tabular format : Token | Purpose | Users

  • Token, Users and Roles

    • What tokens are used in the DMP APD Server, Which can use what token and the purpose of using the token in a tabular format : API | Users | Token

  • Users and Roles

    • What are the flow for each user, or what services can the consumer or provider could make use of
    • Diagram : https://drive.google.com/file/d/1W69dMniLSBl6iyetvBYUtkjS5Yf0xxV-/view

  • Terminologies and Definitions

    • Those words that are commonly used in the server that would help the consumers, providers to get started with the server by understanding the jargons

• docs/FAQ.md

  • Frequently occuring issues or problems, questions, gaps can be listed here
  • This markdown file could be updated as and when a new question is asked or discussed

• docs/Setup_and_Installation.md

  • Setup and Installation Guide: helps in the deployment of the server

    • Configurations: Reference the Configurations.md here
    • Dependencies:
      • List down external and internal dependencies used by the server
    • Prerequisites: to be added wrt each server
      • Keycloak registration for DX DMP APD as trustee and APD
      • RabbitMQ configurations
        • vhost, exchange, queue to exchange, user permissions in a tabular format
        • body for the API request
    • Reference: https://docs.google.com/document/d/17zJ-9LgW7izTo0h4sjKmcL-ZilSjZUneq-Yo_ydcI7g/edit#heading=h.q8ebfatvlign
      • PostgresQL
        • Setup of db and markdown table for : Table name | Purpose
      • Auditing
        • why and where is auditing done
        • markdown table for auditing : Table name | Purpose
        • Reference : Postgres and Immudb auditing table schema along with the indexes from auditing server
      • Database migration using flyway
        • Where are the flyway files
        • Why is db migration done
        • commands to do the db migration

    • Installation Steps:

      • Maven
      • JAR
      • Docker

    • Logging and Monitoring

      • log4j 2
        • why is it used, related files that the user can configure, any references
      • Micrometer
        • why is it used, related files references

    • Testing

      • Unit Testing
        • why is it done, commands to run unit tests, any prerequisites, related files, commands to run
      • Integration Testing
        • prerequisites for running integration tests, why is it done, related files, commands to run

    • Performance Testing

      • JMeter
        • why is Jmeter used, command to generate report, references

    • Security testing

      • Zed Attack Proxy
        • why is ZAP used, references

• docs/Solution_Architecture.md

  • Diagram: https://www.google.com/url?q=https://drive.google.com/file/d/1MTkFf4t2VasWSIAwDQotm0Dy-tkPzZZN/view?usp%3Dsharing&sa=D&source=docs&ust=172595396576
  • Brief info about all the modules and services offered by the server to the user
  • Reference: IUDX Design Document for the respective server : https://docs.google.com/document/d/1j289zdt2n5i81vvwJJl-lJB-D4Ld8ihQajjN3qZuGM8/edit

• docs/Tutorials.md: optional

  • reference any tutorial wrt server configuration, deployment, services, flows

• docs/openapi.yaml

  • Remove references of IUDX and replace it with CDPG

  contact:
  name: For support contact CDPG Team at
  email: [email protected]
  url: https://dataforpublicgood.org.in/
  license:
  name: Apache 2.0

• /src/test/resources/README.md:

  • Making base path configurable in the postman environment
  • Key value pairs used in the postman environment in a markdown table: Key| Value Example | Description

• /src/test/resources/resources/DX-Catalogue-Items/RESOURCES_USED.md:

  • Mention DX catalogue items used in the server in different flows for maintaining the lifecycle of the resources

Key	item ID	Purpose (unit testing, integration testing, other)	Details (the flow in which it is being used)

• .github/ISSUE_TEMPLATE/bug-report.md

  • reference : https://github.com/datakaveri/dx-acl-apd/blob/main/.github/ISSUE_TEMPLATE/bug-report.md
  • template to create an issue on the repo

• .github/ISSUE_TEMPLATE/new-feature.md

  • reference : https://github.com/datakaveri/dx-acl-apd/blob/main/.github/ISSUE_TEMPLATE/new-feature.md
  • template to add a feature on the repo

• .github/PULL_REQUEST_TEMPLATE.md

  • reference: https://github.com/datakaveri/dx-acl-apd/blob/main/.github/PULL_REQUEST_TEMPLATE.md
  • template for every pull request

• Wiki: for wiki, github actions are defined under .github/workflows/ as docker-image.yml, move_docs.yml, update_wiki.yml

  • reference : https://github.com/datakaveri/dx-acl-apd/tree/main/.github/workflows