From fe887fd332ab53275825ac64634d8fab91559de3 Mon Sep 17 00:00:00 2001 From: Venkatesh Babu Date: Tue, 2 Apr 2024 13:16:27 +0530 Subject: [PATCH 1/2] Add FAQ --- README.md | 31 +++++--------------------- docs/contribution.md | 19 ++++++++++++++++ docs/faq.md | 28 +++++++++++++++++++++++ docs/notes/mandatory_layer_2_config.md | 22 ++++++++++++++++++ 4 files changed, 75 insertions(+), 25 deletions(-) create mode 100644 docs/contribution.md create mode 100644 docs/faq.md create mode 100644 docs/notes/mandatory_layer_2_config.md diff --git a/README.md b/README.md index c34f89a..f835321 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,17 @@ # Beckn-ONIX -Beckn-ONIX - Open Network In A Box, is a project designed to effortlessly set up and maintain Beckn network that is scalable, secure and easy to maintain. +Beckn ONIX is [FIDE](https://fide.org/) project aimed at easing setup and maintainance of a [Beckn](https://becknprotocol.io/) Network using reference implementations. Objectives include setting up reliable, configurable and fast Beckn network as a virtual appliance. This initiative is independent of the evolution of the Beckn protocol. This effort is also aimed at inviting contributions from the community to create secure, reliable builds for production environments. -In the install folder, you find a tool that helps install a Beckn network. This tool serves as a valuable resource for developers and network participants eager to explore Beckn protocols or join open networks supported by the Beckn protocol. By simplifying the installation process, Beckn-ONIX streamlines the onboarding experience. +Within the install folder you will find a `beckn-onix.sh` file which is an installer that helps create a multi-node Beckn network using reference implementations Refer to the following documents for more information: - [User Guide](./docs/user_guide.md) -- [Step by step walkthrough of a demo](./docs/demo_walkthrough.md) +- [Step by step walkthrough of a demo installation](./docs/demo_walkthrough.md) +- [Frequently asked questions (FAQ)](./docs/faq.md) - [release notes](./install/RELEASE.md) Experience the convenience and efficiency of Beckn-ONIX as you embark on your journey with Beckn protocols and open networks. -## Note on mandatory Layer 2 Config (Important) - -This note will eventually be moved to a proper place in the documentation. It has been put here to alert people who run Beckn-ONIX in the meantime. -Beckn-ONIX mandates availability of Layer 2 Config for a particular domain before any transactions can be conducted on it. If the layer 2 config is not present, on either the BAP or the BPP, the following error is returned back to the caller. "Config error : Layer 2 config not found." - -Usually the network facilitators will host the Layer 2 config and provide a way to access it. Currently we have a small script (layer2/download_layer_2_config_bap.sh and layer2/download_layer_2_config_bpp.sh) that can download the layer 2 config from a fixed location and insert it into the docker container that runs the Protocol Server Client. - -If you have the Layer 2 config file with you and not hosted, you can use the following procedure to update it manually. In case you do not have layer 2 config file with you, as developer machine workaround, you can copy the core_version.yaml(e.g. core_1.1.0.yaml) and rename it as the layer 2 config for a domain (e.g. for a domain named retail for core version 1.1.0, retail_1.1.0.yaml). This is strictly not recommended for production networks. - -Process to manually update layer 2 config. - -``` -docker cp "$FILENAME" "$CONTAINER_NAME":"$CONTAINER_PATH/$FILENAME" - -# example -docker cp retail_1.1.0.yaml bap-client:/usr/src/app/schemas/retail_1.1.0.yaml -docker cp retail_1.1.0.yaml bap-network:/usr/src/app/schemas/retail_1.1.0.yaml - -docker cp retail_1.1.0.yaml bpp-client:/usr/src/app/schemas/retail_1.1.0.yaml -docker cp retail_1.1.0.yaml bpp-netork:/usr/src/app/schemas/retail_1.1.0.yaml - -``` +**Note on mandatory Layer 2 Config (Important)** +Please refer to this [note on mandatory layer 2 configuration](./docs/notes/mandatory_layer_2_config.md). diff --git a/docs/contribution.md b/docs/contribution.md new file mode 100644 index 0000000..2c60789 --- /dev/null +++ b/docs/contribution.md @@ -0,0 +1,19 @@ +## Contribution + +We welcome contribution from the community both for Beckn-ONIX project as well as initiatives to add such tools in different production environment. Use the following process to contribute to this project + +### Process to raise issues + +- Check in the [issues](https://github.com/beckn/beckn-onix/issues) section to see if a similar issue or enhancement has been already raised +- If there is an issue already present, use the comment facility in the issue to add your input +- If there is no issue and you feel it needs to be raised, use the New Issue button. A template will be present. Use it to fill the various parts. +- Track the issue you raised and communicate using comments + +### Process to fix issues + +- Once an issue has been raised and validated, any interested contributor can assign it to himself and work on it. +- Use the comment section of the issue to develop any concensus or for clarification +- Use the [forking and raising pull request](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) guide here for the process of making your change and asking for it to be incorporated in the project +- Use the mentions (@ symbol followed by username e.g. @jjohn) to draw attention to the maintainers of the project. Usually the person committing the last few commits on the main branch is a good candidate to approach +- Once the maintainer has agreed with the changes, he will merge the changes into the right branch based on the branching strategy of the project. +- The issue will be closed after validation. diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..a57be16 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,28 @@ +## Beckn-ONIX FAQ + +**Q: What is Beckn-ONIX?** +**A:** Beckn ONIX is [FIDE](https://fide.org/) project aimed at easing setup and maintainance of a [Beckn](https://becknprotocol.io/) Network using reference implementations. Objectives include setting up reliable, configurable and fast Beckn network as a virtual appliance. + +**Q: Is Beckn-ONIX a protocol? Is Beckn-ONIX a new version of Beckn?** +**A:** No Beckn-ONIX is not a protocol. Beckn-ONIX is not a new version of Beckn. Beckn-ONIX project just helps setup and maintain a Beckn network. This initiative is independent of the evolution of Beckn + +**Q: What components are installed when we setup a Beckn network with Beckn-ONIX?** +**A:** When you setup a new Beckn network using Beckn-ONIX, the reference implementations of [Beckn Registry](https://github.com/beckn/beckn-registry-app), [Beckn Gateway](https://github.com/beckn/beckn-gateway-app), [BAP Beckn Adapter](https://github.com/beckn/protocol-server) and [BPP Beckn Adapter](https://github.com/beckn/protocol-server) + +**Q: Do I need anything more than Beckn-ONIX to do transactions?** +**A:** Yes. Beckn-ONIX only installs the core network components. Refer to the [Sample deployment diagram](./user_guide.md/#sample-deployment-diagram) for a simple illustration of the various components. As you see in that diagram, apart from the core network components, you would need a buyer side application and a seller side application to perform transactions. Typically you will be implementing one or both of these. If you are only implementing one side of it, you can use sample applications or postman as the other application. + +**Q: Do I have to use Beckn-ONIX to install these reference components?** +**A:** No. If you are comfortable you can install the reference implementations of [Beckn Registry](https://github.com/beckn/beckn-registry-app), [Beckn Gateway](https://github.com/beckn/beckn-gateway-app), [BAP Beckn Adapter](https://github.com/beckn/protocol-server) and [BPP Beckn Adapter](https://github.com/beckn/protocol-server) directly from the repositories. Beckn-ONIX makes the tasks easier through guided installation. + +**Q: Do I have to use these reference components to get onto Beckn network? Can I write them myself** +**A:** Sure. As the name suggests, these are just reference components and their objective is to get you started easily. You can however write your own implementation of the Beckn protocol using the tech stack you like. + +**Q: The user guide mentions Nginx for reverse proxy. Can I use any other program as reverse proxy** +**A:** Yes. You can use other programs. The user guide uses Nginx primarily as an example. The instructions to configure the reverse proxy might change. In particular, for the flow we have you might need to identify how to install SSL certificates and how to proxy a request to a port based on the requested URL. + +**Q: Is Beckn-ONIX the best way to setup and manage Beckn network?** +**A:** No. Beckn-ONIX is just one effort to kick start the process of creating tools to aid easy creation and operation of Beckn networks. We want the community to create even better tools for different production environments. + +**Q: How do I contribute to this project?** +**A:** We welcome contributions both to this project as well as initiatives in other production environment. Refer to the [contribution guide](./contribution.md) for more details on the process. diff --git a/docs/notes/mandatory_layer_2_config.md b/docs/notes/mandatory_layer_2_config.md new file mode 100644 index 0000000..db39310 --- /dev/null +++ b/docs/notes/mandatory_layer_2_config.md @@ -0,0 +1,22 @@ +## Note on mandatory Layer 2 Config (Important) + +This note will eventually be moved to a proper place in the documentation. It has been put here to alert people who run Beckn-ONIX in the meantime. +Beckn-ONIX mandates availability of Layer 2 Config for a particular domain before any transactions can be conducted on it. If the layer 2 config is not present, on either the BAP or the BPP, the following error is returned back to the caller. "Config error : Layer 2 config not found." + +Usually the network facilitators will host the Layer 2 config and provide a way to access it. Currently we have a small script (layer2/download_layer_2_config_bap.sh and layer2/download_layer_2_config_bpp.sh) that can download the layer 2 config from a fixed location and insert it into the docker container that runs the Protocol Server Client. + +If you have the Layer 2 config file with you and not hosted, you can use the following procedure to update it manually. In case you do not have layer 2 config file with you, as developer machine workaround, you can copy the core_version.yaml(e.g. core_1.1.0.yaml) and rename it as the layer 2 config for a domain (e.g. for a domain named retail for core version 1.1.0, retail_1.1.0.yaml). This is strictly not recommended for production networks. + +Process to manually update layer 2 config. + +``` +docker cp "$FILENAME" "$CONTAINER_NAME":"$CONTAINER_PATH/$FILENAME" + +# example +docker cp retail_1.1.0.yaml bap-client:/usr/src/app/schemas/retail_1.1.0.yaml +docker cp retail_1.1.0.yaml bap-network:/usr/src/app/schemas/retail_1.1.0.yaml + +docker cp retail_1.1.0.yaml bpp-client:/usr/src/app/schemas/retail_1.1.0.yaml +docker cp retail_1.1.0.yaml bpp-netork:/usr/src/app/schemas/retail_1.1.0.yaml + +``` From 72abd80acca629145710fea7a524823299e18d9e Mon Sep 17 00:00:00 2001 From: Venkatesh Babu Date: Tue, 2 Apr 2024 13:23:04 +0530 Subject: [PATCH 2/2] Add FAQ --- README.md | 2 +- docs/demo_walkthrough.md | 6 +++--- docs/faq.md | 2 +- docs/user_guide.md | 2 +- install/beckn-onix.sh | 2 +- 5 files changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index f835321..f23a544 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Beckn-ONIX -Beckn ONIX is [FIDE](https://fide.org/) project aimed at easing setup and maintainance of a [Beckn](https://becknprotocol.io/) Network using reference implementations. Objectives include setting up reliable, configurable and fast Beckn network as a virtual appliance. This initiative is independent of the evolution of the Beckn protocol. This effort is also aimed at inviting contributions from the community to create secure, reliable builds for production environments. +Beckn-ONIX is [FIDE](https://fide.org/) project aimed at easing setup and maintainance of a [Beckn](https://becknprotocol.io/) Network using reference implementations. Objectives include setting up reliable, configurable and fast Beckn network as a virtual appliance. This initiative is independent of the evolution of the Beckn protocol. This effort is also aimed at inviting contributions from the community to create secure, reliable builds for production environments. Within the install folder you will find a `beckn-onix.sh` file which is an installer that helps create a multi-node Beckn network using reference implementations diff --git a/docs/demo_walkthrough.md b/docs/demo_walkthrough.md index ab9a5b8..2a61f96 100644 --- a/docs/demo_walkthrough.md +++ b/docs/demo_walkthrough.md @@ -2,7 +2,7 @@ ## Introduction -This document describes setting up of a [Beckn network](https://becknprotocol.io/) with Beckn ONIX and conducting transactions in a couple of domains (retail and energy). The general flow will involve the following steps: +This document describes setting up of a [Beckn network](https://becknprotocol.io/) with Beckn-ONIX and conducting transactions in a couple of domains (retail and energy). The general flow will involve the following steps: - [Setup the prerequisites](#overall-prerequisites) - [Create a new network and install the registry](#create-a-new-network-and-install-the-registry) @@ -63,7 +63,7 @@ cd beckn-onix/install - In the prompt that comes up, choose setting up a new network. ``` -Beckn ONIX is a platform that helps you quickly launch and configure beckn-enabled networks. +Beckn-ONIX is a platform that helps you quickly launch and configure beckn-enabled networks. What would you like to do? 1. Join an existing network @@ -160,7 +160,7 @@ cd beckn-onix/install - In the prompt that comes up, choose joining an existing network. ``` -Beckn ONIX is a platform that helps you quickly launch and configure beckn-enabled networks. +Beckn-ONIX is a platform that helps you quickly launch and configure beckn-enabled networks. What would you like to do? 1. Join an existing network diff --git a/docs/faq.md b/docs/faq.md index a57be16..05fc248 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,7 +1,7 @@ ## Beckn-ONIX FAQ **Q: What is Beckn-ONIX?** -**A:** Beckn ONIX is [FIDE](https://fide.org/) project aimed at easing setup and maintainance of a [Beckn](https://becknprotocol.io/) Network using reference implementations. Objectives include setting up reliable, configurable and fast Beckn network as a virtual appliance. +**A:** Beckn-ONIX is [FIDE](https://fide.org/) project aimed at easing setup and maintainance of a [Beckn](https://becknprotocol.io/) Network using reference implementations. Objectives include setting up reliable, configurable and fast Beckn network as a virtual appliance. **Q: Is Beckn-ONIX a protocol? Is Beckn-ONIX a new version of Beckn?** **A:** No Beckn-ONIX is not a protocol. Beckn-ONIX is not a new version of Beckn. Beckn-ONIX project just helps setup and maintain a Beckn network. This initiative is independent of the evolution of Beckn diff --git a/docs/user_guide.md b/docs/user_guide.md index f5ef584..377e30d 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -18,7 +18,7 @@ ## Introduction -Beckn ONIX is [FIDE](https://fide.org/) project aimed at easing setup and maintainance of a [Beckn](https://becknprotocol.io/) Network using reference implementations. Objectives include setting up reliable, configurable and fast Beckn network as a virtual appliance. This initiative is independent of the evolution of the Beckn protocol. This effort is also aimed at inviting contributions from the community to create secure, reliable builds for production environments. +Beckn-ONIX is [FIDE](https://fide.org/) project aimed at easing setup and maintainance of a [Beckn](https://becknprotocol.io/) Network using reference implementations. Objectives include setting up reliable, configurable and fast Beckn network as a virtual appliance. This initiative is independent of the evolution of the Beckn protocol. This effort is also aimed at inviting contributions from the community to create secure, reliable builds for production environments. This user guide provides all information necessary to setup a Beckn network and conduct transactions on it. For a better understanding of Beckn and the terminologies associated with the ecosystem, please refer to the [Beckn for Developers site](https://developers.becknprotocol.io/). diff --git a/install/beckn-onix.sh b/install/beckn-onix.sh index 6481761..a933702 100755 --- a/install/beckn-onix.sh +++ b/install/beckn-onix.sh @@ -155,7 +155,7 @@ else echo "[Display Beckn-ONIX ASCII Art]" fi -echo "Beckn ONIX is a platform that helps you quickly launch and configure beckn-enabled networks." +echo "Beckn-ONIX is a platform that helps you quickly launch and configure beckn-enabled networks." echo -e "\nWhat would you like to do?\n1. Join an existing network\n2. Create new production network\n3. Set up a network on your local machine\n4. Merge multiple networks\n5. Configure Existing Network\n(Press Ctrl+C to exit)" read -p "Enter your choice: " choice