Merge pull request #21 from beckn/documentation
Add user guide and step by step demo
This commit is contained in:
Venkatesh Babu
1
.gitignore
vendored
1
.gitignore
vendored
@@ -1,4 +1,5 @@
|
|||||||
# Logs
|
# Logs
|
||||||
|
.DS_Store
|
||||||
logs
|
logs
|
||||||
*.log
|
*.log
|
||||||
npm-debug.log*
|
npm-debug.log*
|
||||||
|
|||||||
10
README.md
10
README.md
@@ -2,11 +2,18 @@
|
|||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
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, ONIX streamlines the onboarding experience. For more details, refer to [release notes](./install/RELEASE.md) and [start with Beckn](./install/START_BECKN.md)
|
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, ONIX streamlines the onboarding experience.
|
||||||
|
|
||||||
|
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)
|
||||||
|
- [release notes](./install/RELEASE.md)
|
||||||
|
|
||||||
Experience the convenience and efficiency of ONIX as you embark on your journey with BECKN protocols and open networks.
|
Experience the convenience and efficiency of ONIX as you embark on your journey with BECKN protocols and open networks.
|
||||||
|
|
||||||
## Note on mandatory Layer 2 Config (Important)
|
## 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.
|
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."
|
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."
|
||||||
|
|
||||||
@@ -15,6 +22,7 @@ Usually the network facilitators will host the Layer 2 config and provide a way
|
|||||||
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.
|
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.
|
Process to manually update layer 2 config.
|
||||||
|
|
||||||
```
|
```
|
||||||
docker cp "$FILENAME" "$CONTAINER_NAME":"$CONTAINER_PATH/$FILENAME"
|
docker cp "$FILENAME" "$CONTAINER_NAME":"$CONTAINER_PATH/$FILENAME"
|
||||||
|
|
||||||
|
|||||||
197
artifacts/ONIX Demo Collection.postman_collection.json
Normal file
197
artifacts/ONIX Demo Collection.postman_collection.json
Normal file
@@ -0,0 +1,197 @@
|
|||||||
|
{
|
||||||
|
"info": {
|
||||||
|
"_postman_id": "303038a6-0aee-4094-b5c3-45fef219cdef",
|
||||||
|
"name": "ONIX Demo Collection",
|
||||||
|
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
|
||||||
|
"_exporter_id": "31540449"
|
||||||
|
},
|
||||||
|
"item": [
|
||||||
|
{
|
||||||
|
"name": "UEI",
|
||||||
|
"item": [
|
||||||
|
{
|
||||||
|
"name": "Search",
|
||||||
|
"request": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"context\": {\n \"domain\": \"uei:charging\",\n \"location\": {\n \"city\": {\n \"name\": \"Bangalore\",\n \"code\": \"std:080\"\n },\n \"country\": {\n \"name\": \"India\",\n \"code\": \"IND\"\n }\n },\n \"action\": \"search\",\n \"version\": \"1.1.0\",\n \"transaction_id\": \"fc24f1e9-6d01-44bf-888c-d5884ca0f66f\",\n \"message_id\": \"{{$randomUUID}}\",\n \"timestamp\": \"2023-10-09T04:46:28.012Z\",\n \"bpp_id\": \"{{bpp_id}}\",\n \"bpp_uri\": \"{{bpp_uri}}\",\n \"bap_id\": \"{{bap_id}}\",\n \"bap_uri\": \"{{bap_uri}}\"\n },\n \"message\": {\n \"intent\": {\n \"location\": {\n \"circle\": {\n \"gps\": \"12.423423,77.325647\",\n \"radius\": {\n \"type\": \"CONSTANT\",\n \"value\": \"5\",\n \"unit\": \"km\"\n }\n }\n }\n }\n }\n}",
|
||||||
|
"options": {
|
||||||
|
"raw": {
|
||||||
|
"language": "json"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{base_url}}/search",
|
||||||
|
"host": [
|
||||||
|
"{{base_url}}"
|
||||||
|
],
|
||||||
|
"path": [
|
||||||
|
"search"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"response": []
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "Select",
|
||||||
|
"request": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"context\": {\n \"domain\": \"{{uei}}\",\n \"location\": {\n \"city\": {\n \"name\": \"Bangalore\",\n \"code\": \"std:080\"\n },\n \"country\": {\n \"name\": \"India\",\n \"code\": \"IND\"\n }\n },\n \"action\": \"select\",\n \"version\": \"1.1.0\",\n \"transaction_id\": \"fc24f1e9-6d01-44bf-888c-d5884ca0f66f\",\n \"message_id\": \"{{$randomUUID}}\",\n \"timestamp\": \"2023-10-09T04:46:28.012Z\",\n \"bpp_id\": \"{{bpp_id}}\",\n \"bpp_uri\": \"{{bpp_uri}}\",\n \"bap_id\": \"{{bap_id}}\",\n \"bap_uri\": \"{{bap_uri}}\"\n },\n \"message\": {\n \"order\": {\n \"provider\": {\n \"id\": \"1\"\n },\n \"items\": [\n {\n \"id\": \"1\"\n }\n ]\n }\n }\n}",
|
||||||
|
"options": {
|
||||||
|
"raw": {
|
||||||
|
"language": "json"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{base_url}}/select",
|
||||||
|
"host": [
|
||||||
|
"{{base_url}}"
|
||||||
|
],
|
||||||
|
"path": [
|
||||||
|
"select"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"response": []
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "Init",
|
||||||
|
"request": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"context\": {\n \"domain\": \"{{uei}}\",\n \"location\": {\n \"city\": {\n \"name\": \"Bangalore\",\n \"code\": \"std:080\"\n },\n \"country\": {\n \"name\": \"India\",\n \"code\": \"IND\"\n }\n },\n \"action\": \"init\",\n \"version\": \"1.1.0\",\n \"transaction_id\": \"fc24f1e9-6d01-44bf-888c-d5884ca0f66f\",\n \"message_id\": \"{{$randomUUID}}\",\n \"timestamp\": \"2023-10-09T04:46:28.012Z\",\n \"bpp_id\": \"{{bpp_id}}\",\n \"bpp_uri\": \"{{bpp_uri}}\",\n \"bap_id\": \"{{bap_id}}\",\n \"bap_uri\": \"{{bap_uri}}\"\n },\n \"message\": {\n \"order\": {\n \"provider\": {\n \"id\": \"1\"\n },\n \"items\": [\n {\n \"id\": \"1\"\n }\n ],\n \"billing\": {\n \"name\": \"Alice Smith\",\n \"address\": \"Apt 303, Maple Towers, Richmond Road, 560001\",\n \"state\": {\n \"name\": \"Jurong East\"\n },\n \"city\": {\n \"name\": \"Jurong East\"\n },\n \"email\": \"alice.smith@example.com\",\n \"phone\": \"9886098860\"\n }\n }\n }\n}",
|
||||||
|
"options": {
|
||||||
|
"raw": {
|
||||||
|
"language": "json"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{base_url}}/init",
|
||||||
|
"host": [
|
||||||
|
"{{base_url}}"
|
||||||
|
],
|
||||||
|
"path": [
|
||||||
|
"init"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"response": []
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "Confirm",
|
||||||
|
"request": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"context\": {\n \"domain\": \"{{uei}}\",\n \"location\": {\n \"city\": {\n \"name\": \"Bangalore\",\n \"code\": \"std:080\"\n },\n \"country\": {\n \"name\": \"India\",\n \"code\": \"IND\"\n }\n },\n \"action\": \"confirm\",\n \"version\": \"1.1.0\",\n \"transaction_id\": \"fc24f1e9-6d01-44bf-888c-d5884ca0f66f\",\n \"message_id\": \"{{$randomUUID}}\",\n \"timestamp\": \"2023-10-09T04:46:28.012Z\",\n \"bpp_id\": \"{{bpp_id}}\",\n \"bpp_uri\": \"{{bpp_uri}}\",\n \"bap_id\": \"{{bap_id}}\",\n \"bap_uri\": \"{{bap_uri}}\"\n },\n \"message\": {\n \"order\": {\n \"items\": [\n {\n \"id\": \"1\"\n }\n ],\n \"fulfillments\": [\n {\n \"id\": \"1\",\n \"customer\": {\n \"contact\": {\n \"email\": \"fox.judie61234@abc.org\",\n \"phone\": \"+91-9999999999\"\n },\n \"person\": {\n \"name\": \"Judie Fox6\"\n }\n }\n }\n ],\n \"billing\": {\n \"name\": \"Industry buyer\",\n \"address\": \"B005 aspire heights, Jurong East, SGP, 680230\",\n \"state\": {\n \"name\": \"Jurong East\"\n },\n \"city\": {\n \"name\": \"Jurong East\"\n },\n \"email\": \"nobody@nomail.com\",\n \"phone\": \"9886098860\"\n }\n }\n }\n}",
|
||||||
|
"options": {
|
||||||
|
"raw": {
|
||||||
|
"language": "json"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{base_url}}/confirm",
|
||||||
|
"host": [
|
||||||
|
"{{base_url}}"
|
||||||
|
],
|
||||||
|
"path": [
|
||||||
|
"confirm"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"response": []
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "Status",
|
||||||
|
"request": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"context\": {\n \"domain\": \"{{uei}}\",\n \"location\": {\n \"city\": {\n \"name\": \"Bangalore\",\n \"code\": \"std:080\"\n },\n \"country\": {\n \"name\": \"India\",\n \"code\": \"IND\"\n }\n },\n \"action\": \"status\",\n \"version\": \"1.1.0\",\n \"transaction_id\": \"fc24f1e9-6d01-44bf-888c-d5884ca0f66f\",\n \"message_id\": \"{{$randomUUID}}\",\n \"timestamp\": \"2023-10-09T04:46:28.012Z\",\n \"bpp_id\": \"{{bpp_id}}\",\n \"bpp_uri\": \"{{bpp_uri}}\",\n \"bap_id\": \"{{bap_id}}\",\n \"bap_uri\": \"{{bap_uri}}\"\n },\n \"message\": {\n \"order_id\": \"1\"\n }\n}",
|
||||||
|
"options": {
|
||||||
|
"raw": {
|
||||||
|
"language": "json"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{base_url}}/status",
|
||||||
|
"host": [
|
||||||
|
"{{base_url}}"
|
||||||
|
],
|
||||||
|
"path": [
|
||||||
|
"status"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"response": []
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"event": [
|
||||||
|
{
|
||||||
|
"listen": "prerequest",
|
||||||
|
"script": {
|
||||||
|
"type": "text/javascript",
|
||||||
|
"exec": [
|
||||||
|
""
|
||||||
|
]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"listen": "test",
|
||||||
|
"script": {
|
||||||
|
"type": "text/javascript",
|
||||||
|
"exec": [
|
||||||
|
""
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"variable": [
|
||||||
|
{
|
||||||
|
"key": "bpp_id",
|
||||||
|
"value": "onix-bpp.becknprotocol.io",
|
||||||
|
"type": "string"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"key": "bpp_uri",
|
||||||
|
"value": "https://onix-bpp.becknprotocol.io",
|
||||||
|
"type": "string"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"key": "bap_id",
|
||||||
|
"value": "onix-bap.becknprotocol.io",
|
||||||
|
"type": "string"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"key": "bap_uri",
|
||||||
|
"value": "https://onix-bap.becknprotocol.io",
|
||||||
|
"type": "string"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"key": "core_version",
|
||||||
|
"value": "1.1.0",
|
||||||
|
"type": "string"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"key": "base_url",
|
||||||
|
"value": "https://onix-bap-client.becknprotocol.io",
|
||||||
|
"type": "string"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
466
docs/demo_walkthrough.md
Normal file
466
docs/demo_walkthrough.md
Normal file
@@ -0,0 +1,466 @@
|
|||||||
|
# Steps to setup a new Beckn network and conduct retail and energy transactions on it
|
||||||
|
|
||||||
|
## 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:
|
||||||
|
|
||||||
|
- [Setup the prerequisites](#overall-prerequisites)
|
||||||
|
- [Create a new network and install the registry](#create-a-new-network-and-install-the-registry)
|
||||||
|
- [Install a gateway for the network](#install-a-gateway-for-the-network)
|
||||||
|
- [Install a Beckn Adaptor for the BAP](#install-a-beckn-adaptor-for-the-bap)
|
||||||
|
- [Install a Beckn Adaptor for the BPP](#install-a-beckn-adaptor-for-the-bpp)
|
||||||
|
- [Change the status of the BAP and BPP on the registry as Subscribed](#change-the-status-of-the-bap-and-bpp-on-registry-to-subscribed)
|
||||||
|
- [Update BAP and BPP with the layer 2 configuration files for the domains we are interested in](#update-bap-and-bpp-with-the-layer-2-configuration-files-for-the-domains-we-are-interested-in)
|
||||||
|
- [Conduct successful transactions on the network](#conduct-successful-transactions-on-the-network)
|
||||||
|
|
||||||
|
For the sake of illustration, all the urls are shown as subdomains of becknprotocol.io. These will not be available for you to configure on your network. When you are installing on your network, replace them with your own domain name. For example when the instruction below says "https://onix-registry.becknprotocol.io", if you own a domain "example.org", then what you enter will be "https://onix-registry.example.org". Of course you can give a different subdomain than `onix-registry`. However you should be consistent in using the same URL wherever registry url is required.
|
||||||
|
|
||||||
|
Some of the outputs listed below might be different when you run the script for the first time. The output depends on whether the required docker containers are present in the machine or not.
|
||||||
|
|
||||||
|
Note: Due to a [known issue](https://github.com/beckn/beckn-onix/issues/11), on certain machines, when the script is run for the first time, it errors out complaining about permission error in accessing docker daemon. Till this issue is fixed, the work around is to exit the terminal and restart the installation in a new terminal.
|
||||||
|
|
||||||
|
Please refer to the [Beckn Onix User Guide](./user_guide.md) for detailed explanation of the below steps.
|
||||||
|
|
||||||
|
## Sample deployment diagram
|
||||||
|
|
||||||
|
The following diagram shows a conceptual view of a multi-node Bekn network that we will be setting up. The urls shown here are the same as those used in the examples.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## Overall prerequisites
|
||||||
|
|
||||||
|
- Setup the following subdomains at the registrar. Refer to [registering or adding domain or subdomain section](./user_guide.md/#appendix-a---registering-or-adding-domain-or-subdomains)
|
||||||
|
|
||||||
|
- https://onix-registry.becknprotocol.io - point to machine with registry
|
||||||
|
- https://onix-gateway.becknprotocol.io - point to machine with gateway
|
||||||
|
- https://onix-bap-client.becknprotocol.io - point to machine with BAP
|
||||||
|
- https://onix-bap.becknprotocol.io - point to machine with BAP
|
||||||
|
- https://onix-bpp-client.becknprotocol.io - point to machine with BPP
|
||||||
|
- https://onix-bpp.becknprotocol.io - point to machine with BPP
|
||||||
|
|
||||||
|
- Configure the reverse proxy to have the right ssl certificate installed for all the addresses above. Refer to [configuring ssl certificates on in reverse proxy](./user_guide.md/#ssl-certificates-configured-in-reverse-proxy) for more details
|
||||||
|
- Configure the reverse proxy with proxy_pass to configure the following routes. Refer to [configuring reverse proxy using proxy_pass](./user_guide.md/#configuring-nginx-reverse-proxy-using-proxy-pass) for details.
|
||||||
|
|
||||||
|
- https://onix-registry.becknprotocol.io to port 3030 on the machine
|
||||||
|
- https://onix-gateway.becknprotocol.io to port 4030 on the machine
|
||||||
|
- https://onix-bap-client.becknprotocol.io to port 5001 on the machine
|
||||||
|
- https://onix-bap.becknprotocol.io to port 5002 on the machine
|
||||||
|
- https://onix-bpp-client.becknprotocol.io to port 6001 on the machine
|
||||||
|
- https://onix-bpp.becknprotocol.io to port 6002 on the machine
|
||||||
|
|
||||||
|
- This guide assumes you have a marketplace or a headless store and want to set it up to work with the Beckn network. It is still useful for people who are developing the buyer side software and want to set it up with the network. In such cases a [sandbox](https://github.com/beckn/beckn-sandbox) might be required to mimic a marketplace or a headless shop.
|
||||||
|
|
||||||
|
## Create a new network and install the registry
|
||||||
|
|
||||||
|
- ssh into the virtual server that will hold the registry, clone the repo, change into the install folder and run the beckn-onix.sh script.
|
||||||
|
|
||||||
|
```
|
||||||
|
git clone https://github.com/beckn/beckn-onix.git
|
||||||
|
cd beckn-onix/install
|
||||||
|
./beckn-onix.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
- 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.
|
||||||
|
|
||||||
|
What would you like to do?
|
||||||
|
1. Join an existing network
|
||||||
|
2. Create new production network
|
||||||
|
3. Set up a network on your local machine
|
||||||
|
4. Merge multiple networks
|
||||||
|
5. Configure Existing Network
|
||||||
|
(Press Ctrl+C to exit)
|
||||||
|
Enter your choice: 2
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
- Further choose Registry as the platform you want to install
|
||||||
|
|
||||||
|
```
|
||||||
|
Which platform would you like to set up?
|
||||||
|
1. Registry
|
||||||
|
2. Gateway
|
||||||
|
3. BAP
|
||||||
|
4. BPP
|
||||||
|
Enter your choice: 1
|
||||||
|
```
|
||||||
|
|
||||||
|
- Skip the option to apply network configuration
|
||||||
|
|
||||||
|
```
|
||||||
|
Proceeding with the setup for Registry...
|
||||||
|
Please provide the network-specific configuration URL.
|
||||||
|
Paste the URL of the network configuration here (or press Enter to skip):
|
||||||
|
```
|
||||||
|
|
||||||
|
- Input the host name where the registry will reside as https://onix-registry.becknprotocol.io
|
||||||
|
|
||||||
|
```
|
||||||
|
No network configuration URL provided, proceeding without it.
|
||||||
|
|
||||||
|
Enter publicly accessible registry URL: https://onix-registry.becknprotocol.io
|
||||||
|
```
|
||||||
|
|
||||||
|
- The installation will complete to indicate that the registry has been installed.
|
||||||
|
|
||||||
|
```
|
||||||
|
................Installing required packages................
|
||||||
|
Docker Bash completion is already installed.
|
||||||
|
docker-compose is already installed.
|
||||||
|
Package Installation is done
|
||||||
|
onix-registry.becknprotocol.io
|
||||||
|
................Installing Registry service................
|
||||||
|
WARN[0000] /home/ec2-user/beckn-onix/install/docker-compose-v2.yml: `version` is obsolete
|
||||||
|
[+] Running 1/1
|
||||||
|
✔ Container registry Started 0.5s
|
||||||
|
Registry installation successful
|
||||||
|
[Installation Logs]
|
||||||
|
Your Registry setup is complete.
|
||||||
|
You can access your Registry at https://onix-registry.becknprotocol.io
|
||||||
|
Process complete. Thank you for using Beckn Onix!
|
||||||
|
```
|
||||||
|
|
||||||
|
## Install a gateway for the network
|
||||||
|
|
||||||
|
Please refer to the [Setting up a gateway](./user_guide.md/#setting-up-a-gateway) section of the user guide for the prerequisites and additional information.
|
||||||
|
|
||||||
|
- On the virtual server that will hold the gateway, clone the repo
|
||||||
|
|
||||||
|
```
|
||||||
|
git clone https://github.com/beckn/beckn-onix.git
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
- Due to a [known issue](https://github.com/beckn/beckn-onix/issues/8) with the new version of gateway, we need to do the following. This will be fixed by the project very soon and this step will not be required then. Open `beckn-onix/install/gateway_data/config/networks/onix.json` in an editor and change its contents to the following
|
||||||
|
|
||||||
|
```
|
||||||
|
{
|
||||||
|
"core_version" : "1.1.0",
|
||||||
|
"registry_id": "onix-registry.becknprotocol.io..LREG",
|
||||||
|
"search_provider_id" : "onix-gateway.becknprotocol.io",
|
||||||
|
"self_registration_supported": true,
|
||||||
|
"subscription_needed_post_registration" : true,
|
||||||
|
"base_url": "https://onix-registry.becknprotocol.io",
|
||||||
|
"registry_url" : "https://onix-registry.becknprotocol.io/subscribers",
|
||||||
|
"extension_package": "in.succinct.beckn.boc",
|
||||||
|
"wild_card" : ""
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- Change into the install folder and run the beckn-onix.sh script.
|
||||||
|
|
||||||
|
```
|
||||||
|
cd beckn-onix/install
|
||||||
|
./beckn-onix.sh
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
- 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.
|
||||||
|
|
||||||
|
What would you like to do?
|
||||||
|
1. Join an existing network
|
||||||
|
2. Create new production network
|
||||||
|
3. Set up a network on your local machine
|
||||||
|
4. Merge multiple networks
|
||||||
|
5. Configure Existing Network
|
||||||
|
(Press Ctrl+C to exit)
|
||||||
|
Enter your choice: 1
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
- Choose the component to install as Gateway
|
||||||
|
|
||||||
|
```
|
||||||
|
Which platform would you like to set up?
|
||||||
|
1. Gateway
|
||||||
|
2. BAP
|
||||||
|
3. BPP
|
||||||
|
Enter your choice: 1
|
||||||
|
```
|
||||||
|
|
||||||
|
- Skip the option to apply network configuration
|
||||||
|
|
||||||
|
```
|
||||||
|
Proceeding with the setup for Gateway...
|
||||||
|
Please provide the network-specific configuration URL.
|
||||||
|
Paste the URL of the network configuration here (or press Enter to skip):
|
||||||
|
```
|
||||||
|
|
||||||
|
- Input the URL of the registry we just now installed https://onix-registry.becknprotocol.io
|
||||||
|
|
||||||
|
```
|
||||||
|
No network configuration URL provided, proceeding without it.
|
||||||
|
|
||||||
|
Enter your registry URL: https://onix-registry.becknprotocol.io
|
||||||
|
```
|
||||||
|
|
||||||
|
- Input the Gateway URL https://onix-gateway.becknprotocol.io
|
||||||
|
|
||||||
|
```
|
||||||
|
Enter publicly accessible gateway URL: https://onix-gateway.becknprotocol.io
|
||||||
|
```
|
||||||
|
|
||||||
|
- The installation will complete to indicate the Gateway has been installed and registered with the registry
|
||||||
|
|
||||||
|
```
|
||||||
|
................Installing required packages................
|
||||||
|
Docker Bash completion is already installed.
|
||||||
|
docker-compose is already installed.
|
||||||
|
Package Installation is done
|
||||||
|
% Total % Received % Xferd Average Speed Time Time Time Current
|
||||||
|
Dload Upload Total Spent Left Speed
|
||||||
|
100 555 0 533 100 22 3551 146 --:--:-- --:--:-- --:--:-- 3724
|
||||||
|
Signing Public Key: LlT+DXNzpEKenZuBfhaRl4vvgRxAI2wm8O7/2vmsb0E=
|
||||||
|
Encryption Public Key: qhlWmkfy6WgzSSsGFc9dDfu3Sm3ZbbFf1bYiG+2RjFw=
|
||||||
|
URL https://onix-registry.becknprotocol.io/subscribers
|
||||||
|
................Installing Gateway service................
|
||||||
|
Creating gateway ... done
|
||||||
|
Registering Gateway in the registry
|
||||||
|
{
|
||||||
|
"SWFHttpResponse" : {
|
||||||
|
"Message" : ""
|
||||||
|
,"Status" : "OK"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
Gateway installation successful
|
||||||
|
[Installation Logs]
|
||||||
|
Your Gateway setup is complete.
|
||||||
|
You can access your Gateway at https://onix-gateway.becknprotocol.io
|
||||||
|
Process complete. Thank you for using Beckn Onix!
|
||||||
|
```
|
||||||
|
|
||||||
|
## Install a Beckn Adaptor for the BAP
|
||||||
|
|
||||||
|
- On the virtual server that will hold the BAP, clone the repo, change into the install folder and run the beckn-onix.sh script.
|
||||||
|
|
||||||
|
```
|
||||||
|
git clone https://github.com/beckn/beckn-onix.git
|
||||||
|
cd beckn-onix/install
|
||||||
|
./beckn-onix.sh
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
- In the prompt that comes up, choose joining an existing network.
|
||||||
|
|
||||||
|
```
|
||||||
|
What would you like to do?
|
||||||
|
1. Join an existing network
|
||||||
|
2. Create new production network
|
||||||
|
3. Set up a network on your local machine
|
||||||
|
4. Merge multiple networks
|
||||||
|
5. Configure Existing Network
|
||||||
|
(Press Ctrl+C to exit)
|
||||||
|
Enter your choice: 1
|
||||||
|
```
|
||||||
|
|
||||||
|
- Choose the component to install as BAP
|
||||||
|
|
||||||
|
```
|
||||||
|
Which platform would you like to set up?
|
||||||
|
1. Gateway
|
||||||
|
2. BAP
|
||||||
|
3. BPP
|
||||||
|
Enter your choice: 2
|
||||||
|
```
|
||||||
|
|
||||||
|
- Skip the option to apply network configuration
|
||||||
|
|
||||||
|
```
|
||||||
|
Proceeding with the setup for BAP...
|
||||||
|
Please provide the network-specific configuration URL.
|
||||||
|
Paste the URL of the network configuration here (or press Enter to skip):
|
||||||
|
```
|
||||||
|
|
||||||
|
- Input the BAP subscriber id - onix-bap.becknprotocol.io
|
||||||
|
- Input the BAP URL - https://onix-bap.becknprotocol.io
|
||||||
|
- Input the subscription endpoint of the registry - https://onix-registry.becknprotocol.io/subscribers
|
||||||
|
|
||||||
|
```
|
||||||
|
Enter BAP Subscriber ID: onix-bap.becknprotocol.io
|
||||||
|
Enter BAP Subscriber URL: https://onix-bap.becknprotocol.io
|
||||||
|
Enter the registry_url(e.g. https://registry.becknprotocol.io/subscribers)https://onix-registry.becknprotocol.io/subscribers
|
||||||
|
```
|
||||||
|
|
||||||
|
- The installation will complete to indicate the BAP Beckn Adaptor has installed.
|
||||||
|
|
||||||
|
```
|
||||||
|
................Installing required packages................
|
||||||
|
Docker Bash completion is already installed.
|
||||||
|
docker-compose is already installed.
|
||||||
|
Package Installation is done
|
||||||
|
................Installing MongoDB................
|
||||||
|
WARN[0000] /home/ubuntu/beckn-onix/install/docker-compose-app.yml: `version` is obsolete
|
||||||
|
[+] Running 1/1
|
||||||
|
✔ Container mongoDB Started 0.4s
|
||||||
|
MongoDB installation successful
|
||||||
|
................Installing RabbitMQ................
|
||||||
|
WARN[0000] /home/ubuntu/beckn-onix/install/docker-compose-app.yml: `version` is obsolete
|
||||||
|
[+] Running 1/1
|
||||||
|
✔ Container rabbitmq Started 0.5s
|
||||||
|
RabbitMQ installation successful
|
||||||
|
................Installing Redis................
|
||||||
|
WARN[0000] /home/ubuntu/beckn-onix/install/docker-compose-app.yml: `version` is obsolete
|
||||||
|
[+] Running 1/1
|
||||||
|
✔ Container redis Started 0.6s
|
||||||
|
Redis installation successful
|
||||||
|
Generating public/private key pair
|
||||||
|
Your Private Key: o1t1TvdFaHU1H+2wDTsCEJgMRU9zdVt20SeFRyT0nyOlZujB4B0XZX1bMlchKBUpHQ65/9BCj6aMzS0Rdf+dRw==
|
||||||
|
Your Public Key: pWboweAdF2V9WzJXISgVKR0Ouf/QQo+mjM0tEXX/nUc=
|
||||||
|
Configuring BAP protocol server
|
||||||
|
Registering BAP protocol server on the registry
|
||||||
|
Network Participant Entry is created. Please login to registry https://onix-registry.becknprotocol.io/subscribers and subscribe you Network Participant.
|
||||||
|
WARN[0000] /home/ubuntu/beckn-onix/install/docker-compose-v2.yml: `version` is obsolete
|
||||||
|
[+] Running 1/1
|
||||||
|
✔ Container bap-client Started 0.4s
|
||||||
|
WARN[0000] /home/ubuntu/beckn-onix/install/docker-compose-v2.yml: `version` is obsolete
|
||||||
|
[+] Running 1/1
|
||||||
|
✔ Container bap-network Started 0.5s
|
||||||
|
Protocol server BAP installation successful
|
||||||
|
[Installation Logs]
|
||||||
|
Your BAP setup is complete.
|
||||||
|
You can access your BAP at https://onix-bap.becknprotocol.io
|
||||||
|
Process complete. Thank you for using Beckn Onix!
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
## Install a Beckn Adaptor for the BPP
|
||||||
|
|
||||||
|
- On the virtual server that will hold the BPP, clone the repo, change into the install folder and run the beckn-onix.sh script.
|
||||||
|
|
||||||
|
```
|
||||||
|
git clone https://github.com/beckn/beckn-onix.git
|
||||||
|
cd beckn-onix/install
|
||||||
|
./beckn-onix.sh
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
- In the prompt that comes up, choose joining an existing network.
|
||||||
|
|
||||||
|
```
|
||||||
|
What would you like to do?
|
||||||
|
1. Join an existing network
|
||||||
|
2. Create new production network
|
||||||
|
3. Set up a network on your local machine
|
||||||
|
4. Merge multiple networks
|
||||||
|
5. Configure Existing Network
|
||||||
|
(Press Ctrl+C to exit)
|
||||||
|
Enter your choice: 1
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
- Choose the component to install as BPP
|
||||||
|
|
||||||
|
```
|
||||||
|
Which platform would you like to set up?
|
||||||
|
1. Gateway
|
||||||
|
2. BAP
|
||||||
|
3. BPP
|
||||||
|
Enter your choice: 3
|
||||||
|
```
|
||||||
|
|
||||||
|
- Skip the option to apply network configuration
|
||||||
|
|
||||||
|
```
|
||||||
|
Proceeding with the setup for BPP...
|
||||||
|
Please provide the network-specific configuration URL.
|
||||||
|
Paste the URL of the network configuration here (or press Enter to skip):
|
||||||
|
```
|
||||||
|
|
||||||
|
- Input BPP subscriber id as onix-bpp.becknprotocol.io
|
||||||
|
- Input the BPP URL as https://onix-bpp.becknprotocol.io
|
||||||
|
- Input the registry URL to subscribe as https://onix-registry.becknprotocol.io/subscribers
|
||||||
|
- Input the webhook URL as the endpoint where your seller app or marketplace is. In case you do not have one, you can try 'https://unified-bpp.becknprotocol.io/beckn-bpp-adapter'. However the availability of a seller software for ever at this endpoint is not guaranteed (It currently is present)
|
||||||
|
|
||||||
|
```
|
||||||
|
Enter BPP Subscriber ID: onix-bpp.becknprotocol.io
|
||||||
|
Enter BPP Subscriber URL: https://onix-bpp.becknprotocol.io
|
||||||
|
Enter the registry_url(e.g. https://registry.becknprotocol.io/subscribers): https://onix-registry.becknprotocol.io/subscribers
|
||||||
|
Enter Webhook URL: https://unified-bpp.becknprotocol.io/beckn-bpp-adapter
|
||||||
|
```
|
||||||
|
|
||||||
|
- The installation will complete to indicate the BPP Beckn Adaptor has installed.
|
||||||
|
|
||||||
|
```
|
||||||
|
................Installing required packages................
|
||||||
|
Docker Bash completion is already installed.
|
||||||
|
docker-compose is already installed.
|
||||||
|
Package Installation is done
|
||||||
|
................Installing MongoDB................
|
||||||
|
WARN[0000] /home/ec2-user/beckn-onix/install/docker-compose-app.yml: `version` is obsolete
|
||||||
|
[+] Running 1/1
|
||||||
|
✔ Container mongoDB Started 0.4s
|
||||||
|
MongoDB installation successful
|
||||||
|
................Installing RabbitMQ................
|
||||||
|
WARN[0000] /home/ec2-user/beckn-onix/install/docker-compose-app.yml: `version` is obsolete
|
||||||
|
[+] Running 1/1
|
||||||
|
✔ Container rabbitmq Started 0.6s
|
||||||
|
RabbitMQ installation successful
|
||||||
|
................Installing Redis................
|
||||||
|
WARN[0000] /home/ec2-user/beckn-onix/install/docker-compose-app.yml: `version` is obsolete
|
||||||
|
[+] Running 1/1
|
||||||
|
✔ Container redis Started 0.6s
|
||||||
|
Redis installation successful
|
||||||
|
................Installing Protocol Server for BPP................
|
||||||
|
Generating public/private key pair
|
||||||
|
Configuring BAP protocol server
|
||||||
|
Registering BPP protocol server on the registry
|
||||||
|
Network Participant Entry is created. Please login to registry https://onix-registry.becknprotocol.io/subscribers and subscribe you Network Participant.
|
||||||
|
WARN[0000] /home/ec2-user/beckn-onix/install/docker-compose-v2.yml: `version` is obsolete
|
||||||
|
[+] Running 1/1
|
||||||
|
✔ Container bpp-client Started 0.4s
|
||||||
|
WARN[0000] /home/ec2-user/beckn-onix/install/docker-compose-v2.yml: `version` is obsolete
|
||||||
|
[+] Running 1/1
|
||||||
|
✔ Container bpp-network Started 0.5s
|
||||||
|
Protocol server BPP installation successful
|
||||||
|
[Installation Logs]
|
||||||
|
Your BPP setup is complete.
|
||||||
|
You can access your BPP at https://onix-bpp.becknprotocol.io
|
||||||
|
Process complete. Thank you for using Beckn Onix!
|
||||||
|
```
|
||||||
|
|
||||||
|
## Change the status of the BAP and BPP on registry to Subscribed
|
||||||
|
|
||||||
|
The newly added BAP and BPP should be transitioned to the "SUBSCRIBED" state in the registry.
|
||||||
|
|
||||||
|
- Login to the newly installed registry (e.g. https://onix-registry.becknprotocol.io). The default username and password are root/root
|
||||||
|
- In the Admin menu, click Network Participant
|
||||||
|
- Click the pencil icon next to the onix-bap.becknprotocol.io
|
||||||
|
- Click on the Network Role tab
|
||||||
|
- Click on the pencil icon in the row of onix-bap.becknprotocol.io
|
||||||
|
- Change the status to SUBSCRIBED
|
||||||
|
- Click the Done button.
|
||||||
|
|
||||||
|
- In the Admin menu, click Network Participant
|
||||||
|
- Click the pencil icon next to the onix-bpp.becknprotocol.io
|
||||||
|
- Click on the Network Role tab
|
||||||
|
- Click on the pencil icon in the row of onix-bpp.becknprotocol.io
|
||||||
|
- Change the status to SUBSCRIBED
|
||||||
|
- Click the Done button.
|
||||||
|
|
||||||
|
## Update BAP and BPP with the layer 2 configuration files for the domains we are interested in
|
||||||
|
|
||||||
|
The installation so far has installed a core Beckn network with the registry, gateway, BAP and the BPP. We cannot perform tranasctions on it till we have a layer 2 config file installed for the domains we want to transact in.
|
||||||
|
|
||||||
|
- Login to the virtual server with the BAP
|
||||||
|
- Change into the beckn-onix/layer2 folder
|
||||||
|
- Run the download_layer_2_config_bap.sh file.
|
||||||
|
- Specify the path to the layer 2 config file for the domain of interest. For example, for retail, we have https://raw.githubusercontent.com/beckn/beckn-onix/main/layer2/samples/retail_1.1.0.yaml and for energy https://raw.githubusercontent.com/beckn/beckn-onix/main/layer2/samples/uei_charging_1.1.0.yaml
|
||||||
|
|
||||||
|
- Login to the virtual server with the BPP
|
||||||
|
- Change into the beckn-onix/layer2 folder
|
||||||
|
- Run the download_layer_2_config_bpp.sh file.
|
||||||
|
- Specify the path to the layer 2 config file for the domain of interest. For example, for retail, we have https://raw.githubusercontent.com/beckn/beckn-onix/main/layer2/samples/retail_1.1.0.yaml and for energy https://raw.githubusercontent.com/beckn/beckn-onix/main/layer2/samples/uei_charging_1.1.0.yaml
|
||||||
|
|
||||||
|
- Now with these layer 2 configs installed, we can conduct retail and energy transactions on the network.
|
||||||
|
|
||||||
|
## Conduct successful transactions on the network
|
||||||
|
|
||||||
|
- Load the collection available at `artifacts\ONIX Demo Collection.postman_collection.json` in this repo.
|
||||||
|
- Run the UEI >> Search request
|
||||||
|
- The request should succeed without any errors.
|
||||||
|
- Additional folders and tests will be addded to this collection.
|
||||||
BIN
docs/images/sample_deployment.png
Normal file
BIN
docs/images/sample_deployment.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 50 KiB |
516
docs/sample_nginx_configurations.md
Normal file
516
docs/sample_nginx_configurations.md
Normal file
@@ -0,0 +1,516 @@
|
|||||||
|
# Nginx sample configuration for the different components
|
||||||
|
|
||||||
|
This document lists the various Nginx configuration sample files used in the demo. These use the URLs used as example in the user guide and demo walkthrough. These can be used as a reference.
|
||||||
|
|
||||||
|
## Nginx sample configuration for Registry
|
||||||
|
|
||||||
|
Here is a sample Nginx configuration file for the registry. It uses the 'https://onix-registry.becnkprotocol.io' as the example Registry URL.
|
||||||
|
|
||||||
|
```
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
listen [::]:80;
|
||||||
|
server_name onix-registry.becknprotocol.io;
|
||||||
|
|
||||||
|
return 301 https://$host$request_uri;
|
||||||
|
}
|
||||||
|
|
||||||
|
server {
|
||||||
|
listen 443 ssl;
|
||||||
|
listen [::]:443 ssl;
|
||||||
|
underscores_in_headers on;
|
||||||
|
gzip on;
|
||||||
|
gzip_disable "msie6";
|
||||||
|
gzip_vary on;
|
||||||
|
gzip_proxied any;
|
||||||
|
gzip_comp_level 6;
|
||||||
|
gzip_buffers 16 8k;
|
||||||
|
gzip_http_version 1.1;
|
||||||
|
gzip_min_length 256;
|
||||||
|
gzip_types text/plain text/css application/json application/x-javascript text/xml application/xml application/xml+rss application/javascript text/javascript application/vnd.ms-fontobject application/x-font-ttf font/opentype image/svg+xml image/x-icon font/woff font/woff2 application/octet-stream font/ttf ;
|
||||||
|
|
||||||
|
server_name onix-registry.becknprotocol.io;
|
||||||
|
|
||||||
|
ssl_certificate /etc/letsencrypt/live/onix-registry.becknprotocol.io/fullchain.pem;
|
||||||
|
ssl_certificate_key /etc/letsencrypt/live/onix-registry.becknprotocol.io/privkey.pem;
|
||||||
|
#include /etc/letsencrypt/options-ssl-nginx.conf;
|
||||||
|
#ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
|
||||||
|
|
||||||
|
access_log /var/log/nginx/app_beckn_registry_access.log;
|
||||||
|
error_log /var/log/nginx/app_beckn_registry_error.log debug;
|
||||||
|
client_max_body_size 10M;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
if ($uri ~* "\.(jpg|jpeg|png|gif|ico|ttf|eot|svg|woff|woff2|css|js)$") {
|
||||||
|
add_header 'Cache-Control' 'no-cache';
|
||||||
|
}
|
||||||
|
|
||||||
|
#aio threads=default;
|
||||||
|
|
||||||
|
proxy_set_header Host $http_host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
|
||||||
|
#proxy_http_version 1.1;
|
||||||
|
proxy_set_header X-URIScheme https;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
|
||||||
|
proxy_pass "http://localhost:3030";
|
||||||
|
|
||||||
|
|
||||||
|
set $cors 'true';
|
||||||
|
|
||||||
|
# if ($http_origin ~ '^https?://(localhost|registry-energy\.becknprotocol\.io)$') {
|
||||||
|
# set $cors 'true';
|
||||||
|
# }
|
||||||
|
#
|
||||||
|
add_header 'Access-Control-Allow-Origin' "$http_origin" always;
|
||||||
|
|
||||||
|
if ($cors = 'true') {
|
||||||
|
add_header 'Access-Control-Allow-Credentials' 'true' always;
|
||||||
|
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
|
||||||
|
add_header 'Access-Control-Allow-Headers' 'Accept,Authorization,Cache-Control,Content-Type,DNT,If-Modified-Since,Keep-Alive,Origin,User-Agent,X-Requested-With,Range,ApiKey,pub_key_format' always;
|
||||||
|
}
|
||||||
|
|
||||||
|
if ($request_method = 'OPTIONS') {
|
||||||
|
add_header 'Access-Control-Allow-Origin' "$http_origin" always;
|
||||||
|
add_header 'Access-Control-Allow-Credentials' 'true' always;
|
||||||
|
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
|
||||||
|
add_header 'Access-Control-Allow-Headers' 'Accept,Authorization,Cache-Control,Content-Type,DNT,If-Modified-Since,Keep-Alive,Origin,User-Agent,X-Requested-With,Range,ApiKey,pub_key_format' always;
|
||||||
|
add_header 'Access-Control-Max-Age' 1728000;
|
||||||
|
add_header 'Content-Type' 'text/plain charset=UTF-8';
|
||||||
|
add_header 'Content-Length' 0;
|
||||||
|
return 204;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Nginx sample configuration for Gateway
|
||||||
|
|
||||||
|
Here is a sample Nginx configuration for the gateway. It uses the 'https://onix-gateway.becknprotocol.io' as the example Gateway URL.
|
||||||
|
|
||||||
|
```
|
||||||
|
server {
|
||||||
|
server_name onix-gateway.becknprotocol.io;
|
||||||
|
|
||||||
|
gzip on;
|
||||||
|
gzip_disable "msie6";
|
||||||
|
gzip_vary on;
|
||||||
|
gzip_proxied any;
|
||||||
|
gzip_comp_level 6;
|
||||||
|
gzip_buffers 16 8k;
|
||||||
|
gzip_http_version 1.1;
|
||||||
|
gzip_min_length 256;
|
||||||
|
gzip_types text/plain text/css application/json application/x-javascript text/xml application/xml application/xml+rss application/javascript text/javascript application/vnd.ms-fontobject application/x-font-ttf font/opentype image/svg+xml image/x-icon font/woff font/woff2 application/octet-stream font/ttf ;
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
access_log /var/log/nginx/app_beckn_gateway_access.log;
|
||||||
|
error_log /var/log/nginx/app_beckn_gateway_error.log;
|
||||||
|
client_max_body_size 10M;
|
||||||
|
|
||||||
|
### ssl config - customize as per your setup ###
|
||||||
|
keepalive_timeout 70;
|
||||||
|
ignore_invalid_headers off;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
if ($uri ~ "^(.*)\.(jpg|jpeg|png|gif|ico|ttf|eot|svg|woff|woff2|css|js)$") {
|
||||||
|
add_header 'Cache-Control' no-cache ;
|
||||||
|
}
|
||||||
|
aio threads=default ;
|
||||||
|
|
||||||
|
proxy_set_header Host $host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-URIScheme https;
|
||||||
|
proxy_pass http://localhost:4030/;
|
||||||
|
set $cors '';
|
||||||
|
if ($http_origin ~ '^https?://(localhost|onix\-gateway\.becknprotocol\.io)') {
|
||||||
|
set $cors 'true';
|
||||||
|
}
|
||||||
|
add_header 'Access-Control-Allow-Origin' "$http_origin" always;
|
||||||
|
|
||||||
|
if ($cors = 'true') {
|
||||||
|
#add_header 'Access-Control-Allow-Origin' "$http_origin" always;
|
||||||
|
add_header 'Access-Control-Allow-Credentials' 'true' always;
|
||||||
|
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
|
||||||
|
add_header 'Access-Control-Allow-Headers' 'Accept,Authorization,Cache-Control,Content-Type,DNT,If-Modified-Since,Keep-Alive,Origin,User-Agent,X-Requested-With,Range,ApiKey,pub_key_format' always;
|
||||||
|
}
|
||||||
|
|
||||||
|
if ($request_method = 'OPTIONS') {
|
||||||
|
add_header 'Access-Control-Allow-Origin' "$http_origin" always;
|
||||||
|
add_header 'Access-Control-Allow-Credentials' 'true' always;
|
||||||
|
add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, OPTIONS' always;
|
||||||
|
add_header 'Access-Control-Allow-Headers' 'Accept,Authorization,Cache-Control,Content-Type,DNT,If-Modified-Since,Keep-Alive,Origin,User-Agent,X-Requested-With,Range,ApiKey,pub_key_format' always;
|
||||||
|
# Tell client that this pre-flight info is valid for 20 days
|
||||||
|
add_header 'Access-Control-Max-Age' 1728000;
|
||||||
|
add_header 'Content-Type' 'text/plain charset=UTF-8';
|
||||||
|
add_header 'Content-Length' 0;
|
||||||
|
return 204;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
listen 443 ssl; # managed by Certbot
|
||||||
|
ssl_certificate /etc/letsencrypt/live/onix-gateway.becknprotocol.io/fullchain.pem;
|
||||||
|
ssl_certificate_key /etc/letsencrypt/live/onix-gateway.becknprotocol.io/privkey.pem;
|
||||||
|
#include /etc/letsencrypt/options-ssl-nginx.conf;
|
||||||
|
#ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
|
||||||
|
|
||||||
|
}
|
||||||
|
|
||||||
|
server {
|
||||||
|
if ($host = onix-gateway.becknprotocol.io) {
|
||||||
|
return 301 https://$host$request_uri;
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
listen 80;
|
||||||
|
listen [::]:80;
|
||||||
|
server_name onix-gateway.becknprotocol.io;
|
||||||
|
return 404;
|
||||||
|
|
||||||
|
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Nginx sample configuration for BAP
|
||||||
|
|
||||||
|
The BAP requires two URLs. One is for the BAP network (e.g https://onix-bap.becknprotocol.io') which faces the Beckn network. The other is for the BAP client 'https://onix-bap-client.becknprotocol.io' which faces the buyer side applications.
|
||||||
|
|
||||||
|
The following is a sample Nginx configuration for BAP client (e.g 'https://onix-bap-client.becknprotocol.io')
|
||||||
|
|
||||||
|
```
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
listen [::]:80;
|
||||||
|
# Put the server name as website name <website-name>.
|
||||||
|
server_name onix-bap-client.becknprotocol.io;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
# This for Host, Client and Forwarded For
|
||||||
|
#proxy_set_header Host $http_host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
|
||||||
|
# For Web Sockets.
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
|
||||||
|
# For Proxy.
|
||||||
|
proxy_pass "http://localhost:5001";
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
server {
|
||||||
|
listen 443 ssl http2;
|
||||||
|
listen [::]:443 ssl http2;
|
||||||
|
|
||||||
|
# Put the server name as website name <website-name>.
|
||||||
|
server_name onix-bap-client.becknprotocol.io;
|
||||||
|
|
||||||
|
# Point it to the port in which you want to run the server http://localhost:<Port-Number>.
|
||||||
|
location / {
|
||||||
|
# This for Host, Client and Forwarded For
|
||||||
|
#proxy_set_header Host $http_host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
|
||||||
|
# For Web Sockets.
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
|
||||||
|
# For Proxy.
|
||||||
|
proxy_pass "http://localhost:5001";
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
# This is the path to certificate. /etc/letsencrypt/live/<Domain-name>/fullchain.pem
|
||||||
|
ssl_certificate /etc/letsencrypt/live/onix-bap-client.becknprotocol.io/fullchain.pem;
|
||||||
|
|
||||||
|
|
||||||
|
# This is the path to certificate. /etc/letsencrypt/live/<Domain-name>/privkey.pem
|
||||||
|
ssl_certificate_key /etc/letsencrypt/live/onix-bap-client.becknprotocol.io/privkey.pem;
|
||||||
|
|
||||||
|
ssl_session_timeout 1d;
|
||||||
|
ssl_session_cache shared:MozSSL:10m; # about 40000 sessions
|
||||||
|
ssl_session_tickets off;
|
||||||
|
|
||||||
|
# curl https://ssl-config.mozilla.org/ffdhe2048.txt > /path/to/dhparam
|
||||||
|
# ssl_dhparam /path/to/dhparam;
|
||||||
|
|
||||||
|
# intermediate configuration
|
||||||
|
ssl_protocols TLSv1.2 TLSv1.3;
|
||||||
|
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
|
||||||
|
ssl_prefer_server_ciphers on;
|
||||||
|
|
||||||
|
# HSTS (ngx_http_headers_module is required) (63072000 seconds)
|
||||||
|
add_header Strict-Transport-Security "max-age=63072000" always;
|
||||||
|
|
||||||
|
# OCSP stapling
|
||||||
|
ssl_stapling on;
|
||||||
|
ssl_stapling_verify on;
|
||||||
|
|
||||||
|
# verify chain of trust of OCSP response using Root CA and Intermediate certs
|
||||||
|
# ssl_trusted_certificate /path/to/root_CA_cert_plus_intermediates;
|
||||||
|
|
||||||
|
# replace with the IP address of your resolver
|
||||||
|
resolver 8.8.8.8;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The following is a sample Nginx configuration for BAP Network (e.g. 'https://onix-bap.becknprotocol.io')
|
||||||
|
|
||||||
|
```
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
listen [::]:80;
|
||||||
|
# Put the server name as website name <website-name>.
|
||||||
|
server_name onix-bap.becknprotocol.io;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
# This for Host, Client and Forwarded For
|
||||||
|
#proxy_set_header Host $http_host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
|
||||||
|
# For Web Sockets.
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
|
||||||
|
# For Proxy.
|
||||||
|
proxy_pass "http://localhost:5002";
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
server {
|
||||||
|
listen 443 ssl http2;
|
||||||
|
listen [::]:443 ssl http2;
|
||||||
|
|
||||||
|
# Put the server name as website name <website-name>.
|
||||||
|
server_name onix-bap.becknprotocol.io;
|
||||||
|
|
||||||
|
# Point it to the port in which you want to run the server http://localhost:<Port-Number>.
|
||||||
|
location / {
|
||||||
|
# This for Host, Client and Forwarded For
|
||||||
|
#proxy_set_header Host $http_host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
|
||||||
|
# For Web Sockets.
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
|
||||||
|
# For Proxy.
|
||||||
|
proxy_pass "http://localhost:5002";
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
# This is the path to certificate. /etc/letsencrypt/live/<Domain-name>/fullchain.pem
|
||||||
|
ssl_certificate /etc/letsencrypt/live/onix-bap.becknprotocol.io/fullchain.pem;
|
||||||
|
|
||||||
|
|
||||||
|
# This is the path to certificate. /etc/letsencrypt/live/<Domain-name>/privkey.pem
|
||||||
|
ssl_certificate_key /etc/letsencrypt/live/onix-bap.becknprotocol.io/privkey.pem;
|
||||||
|
|
||||||
|
ssl_session_timeout 1d;
|
||||||
|
ssl_session_cache shared:MozSSL:10m; # about 40000 sessions
|
||||||
|
ssl_session_tickets off;
|
||||||
|
|
||||||
|
# curl https://ssl-config.mozilla.org/ffdhe2048.txt > /path/to/dhparam
|
||||||
|
# ssl_dhparam /path/to/dhparam;
|
||||||
|
|
||||||
|
# intermediate configuration
|
||||||
|
ssl_protocols TLSv1.2 TLSv1.3;
|
||||||
|
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
|
||||||
|
ssl_prefer_server_ciphers on;
|
||||||
|
|
||||||
|
# HSTS (ngx_http_headers_module is required) (63072000 seconds)
|
||||||
|
add_header Strict-Transport-Security "max-age=63072000" always;
|
||||||
|
|
||||||
|
# OCSP stapling
|
||||||
|
ssl_stapling on;
|
||||||
|
ssl_stapling_verify on;
|
||||||
|
|
||||||
|
# verify chain of trust of OCSP response using Root CA and Intermediate certs
|
||||||
|
# ssl_trusted_certificate /path/to/root_CA_cert_plus_intermediates;
|
||||||
|
|
||||||
|
# replace with the IP address of your resolver
|
||||||
|
resolver 8.8.8.8;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Nginx sample configuration for BPP
|
||||||
|
|
||||||
|
The BPP requires two URLs. One is for the BPP Network 'https://onix-bpp.becknprotocol.io' which faces the Beckn network. The other is for the BPP client 'https://onix-bpp-client.becknprotocol.io' which faces the seller side applciation.
|
||||||
|
|
||||||
|
The following is the sample Nginx configuration for BPP client (e.g. 'https://onix-bpp-client.becknprotocol.io')
|
||||||
|
|
||||||
|
```
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
listen [::]:80;
|
||||||
|
# Put the server name as website name <website-name>.
|
||||||
|
server_name onix-bap.becknprotocol.io;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
# This for Host, Client and Forwarded For
|
||||||
|
#proxy_set_header Host $http_host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
|
||||||
|
# For Web Sockets.
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
|
||||||
|
# For Proxy.
|
||||||
|
proxy_pass "http://localhost:5002";
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
server {
|
||||||
|
listen 443 ssl http2;
|
||||||
|
listen [::]:443 ssl http2;
|
||||||
|
|
||||||
|
# Put the server name as website name <website-name>.
|
||||||
|
server_name onix-bap.becknprotocol.io;
|
||||||
|
|
||||||
|
# Point it to the port in which you want to run the server http://localhost:<Port-Number>.
|
||||||
|
location / {
|
||||||
|
# This for Host, Client and Forwarded For
|
||||||
|
#proxy_set_header Host $http_host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
|
||||||
|
# For Web Sockets.
|
||||||
|
proxy_http_version 1.1;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
|
||||||
|
# For Proxy.
|
||||||
|
proxy_pass "http://localhost:5002";
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
# This is the path to certificate. /etc/letsencrypt/live/<Domain-name>/fullchain.pem
|
||||||
|
ssl_certificate /etc/letsencrypt/live/onix-bap.becknprotocol.io/fullchain.pem;
|
||||||
|
|
||||||
|
|
||||||
|
# This is the path to certificate. /etc/letsencrypt/live/<Domain-name>/privkey.pem
|
||||||
|
ssl_certificate_key /etc/letsencrypt/live/onix-bap.becknprotocol.io/privkey.pem;
|
||||||
|
|
||||||
|
ssl_session_timeout 1d;
|
||||||
|
ssl_session_cache shared:MozSSL:10m; # about 40000 sessions
|
||||||
|
ssl_session_tickets off;
|
||||||
|
|
||||||
|
# curl https://ssl-config.mozilla.org/ffdhe2048.txt > /path/to/dhparam
|
||||||
|
# ssl_dhparam /path/to/dhparam;
|
||||||
|
|
||||||
|
# intermediate configuration
|
||||||
|
ssl_protocols TLSv1.2 TLSv1.3;
|
||||||
|
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
|
||||||
|
ssl_prefer_server_ciphers on;
|
||||||
|
|
||||||
|
# HSTS (ngx_http_headers_module is required) (63072000 seconds)
|
||||||
|
add_header Strict-Transport-Security "max-age=63072000" always;
|
||||||
|
|
||||||
|
# OCSP stapling
|
||||||
|
ssl_stapling on;
|
||||||
|
ssl_stapling_verify on;
|
||||||
|
|
||||||
|
# verify chain of trust of OCSP response using Root CA and Intermediate certs
|
||||||
|
# ssl_trusted_certificate /path/to/root_CA_cert_plus_intermediates;
|
||||||
|
|
||||||
|
# replace with the IP address of your resolver
|
||||||
|
resolver 8.8.8.8;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The following is the sample Nginx configuration for BPP Network (e.g. 'https://onix-bpp.becknprotocol.io')
|
||||||
|
|
||||||
|
```
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
listen [::]:80;
|
||||||
|
# Put the server name as website name <website-name>.
|
||||||
|
server_name onix-bpp.becknprotocol.io;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
# This for Host, Client and Forwarded For
|
||||||
|
proxy_set_header Host $http_host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
|
||||||
|
# For Web Sockets.
|
||||||
|
#proxy_http_version 1.1;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
|
||||||
|
# For Proxy.
|
||||||
|
proxy_pass "http://localhost:6002";
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
server {
|
||||||
|
listen 443 ssl http2;
|
||||||
|
listen [::]:443 ssl http2;
|
||||||
|
|
||||||
|
# Put the server name as website name <website-name>.
|
||||||
|
server_name onix-bpp.becknprotocol.io;
|
||||||
|
|
||||||
|
# Point it to the port in which you want to run the server http://localhost:<Port-Number>.
|
||||||
|
location / {
|
||||||
|
# This for Host, Client and Forwarded For
|
||||||
|
proxy_set_header Host $http_host;
|
||||||
|
proxy_set_header X-Real-IP $remote_addr;
|
||||||
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||||
|
|
||||||
|
# For Web Sockets.
|
||||||
|
#proxy_http_version 1.1;
|
||||||
|
proxy_set_header Upgrade $http_upgrade;
|
||||||
|
proxy_set_header Connection "upgrade";
|
||||||
|
|
||||||
|
# For Proxy.
|
||||||
|
proxy_pass "http://localhost:6002";
|
||||||
|
}
|
||||||
|
|
||||||
|
|
||||||
|
# This is the path to certificate. /etc/letsencrypt/live/<Domain-name>/fullchain.pem
|
||||||
|
ssl_certificate /etc/letsencrypt/live/onix-bpp.becknprotocol.io/fullchain.pem;
|
||||||
|
|
||||||
|
|
||||||
|
# This is the path to certificate. /etc/letsencrypt/live/<Domain-name>/privkey.pem
|
||||||
|
ssl_certificate_key /etc/letsencrypt/live/onix-bpp.becknprotocol.io/privkey.pem;
|
||||||
|
|
||||||
|
ssl_session_timeout 1d;
|
||||||
|
ssl_session_cache shared:MozSSL:10m; # about 40000 sessions
|
||||||
|
ssl_session_tickets off;
|
||||||
|
|
||||||
|
# curl https://ssl-config.mozilla.org/ffdhe2048.txt > /path/to/dhparam
|
||||||
|
# ssl_dhparam /path/to/dhparam;
|
||||||
|
|
||||||
|
# intermediate configuration
|
||||||
|
ssl_protocols TLSv1.2 TLSv1.3;
|
||||||
|
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
|
||||||
|
ssl_prefer_server_ciphers on;
|
||||||
|
|
||||||
|
# HSTS (ngx_http_headers_module is required) (63072000 seconds)
|
||||||
|
add_header Strict-Transport-Security "max-age=63072000" always;
|
||||||
|
|
||||||
|
# OCSP stapling
|
||||||
|
ssl_stapling on;
|
||||||
|
ssl_stapling_verify on;
|
||||||
|
|
||||||
|
# verify chain of trust of OCSP response using Root CA and Intermediate certs
|
||||||
|
# ssl_trusted_certificate /path/to/root_CA_cert_plus_intermediates;
|
||||||
|
|
||||||
|
# replace with the IP address of your resolver
|
||||||
|
resolver 8.8.8.8;
|
||||||
|
}
|
||||||
|
```
|
||||||
219
docs/user_guide.md
Normal file
219
docs/user_guide.md
Normal file
@@ -0,0 +1,219 @@
|
|||||||
|
# Beckn ONIX - User Guide
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Introduction](#introduction)
|
||||||
|
- [Running Beckn ONIX on the cloud](#running-beckn-onix-on-the-cloud)
|
||||||
|
- [Sample deployment diagram](#sample-deployment-diagram)
|
||||||
|
- [Overall Prerequisites](#overall-pre-requisites)
|
||||||
|
- [Setting up a new network - Registry](#setting-up-a-new-network---registry)
|
||||||
|
- [Setting up a Gateway](#setting-up-a-gateway)
|
||||||
|
- [Setting up a BAP Beckn Adapter](#setting-up-a-bap-beckn-adapter)
|
||||||
|
- [Setting up a BPP Beckn Adapter](#setting-up-a-bpp-beckn-adapter)
|
||||||
|
- [Downloading Layer 2 Configuration for a domain](#downloading-layer-2-configuration-for-a-domain)
|
||||||
|
- [Testing transactions on the network](#testing-transactions-on-the-new-network)
|
||||||
|
- [Running Beckn ONIX locally](#running-beckn-onix-locally)
|
||||||
|
- [Appendix A - subdomain/domain name configuration](#appendix-a---registering-or-adding-domain-or-subdomains)
|
||||||
|
- [Appendix B - Nginx reverse proxy configuration](#appendix-b---nginx-reverse-proxy-configuration)
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
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/).
|
||||||
|
|
||||||
|
There are two primary setups covered in this document.
|
||||||
|
|
||||||
|
- A typical production setup with the various Beckn components on different nodes - This is explained in the Running Beckn ONIX on the cloud section.
|
||||||
|
- A developer all in one setup - This is explained in the Running Beckn ONIX locally section.
|
||||||
|
|
||||||
|
## Running Beckn ONIX on the Cloud
|
||||||
|
|
||||||
|
Using Beckn ONIX, we can install a Beckn network on the cloud. This will be similar to a simple production instance of Beckn network. In the sections below, we use Amazon EC2 as an example for VPS provider. The guide can be useful for other cloud environments with simple changes on methods of accessing them etc. In this part of the guide, we explain installation of the four components of Registry, Gateway, BAP and BPP Beckn Adapter on different instances of virtual servers. You can however use the same process with minimal changes to install multiple nodes on the same virtual server (e.g. Registry and Gateway on a single virtual server)
|
||||||
|
|
||||||
|
### Sample deployment diagram
|
||||||
|
|
||||||
|
The following diagram shows a conceptual view of a multi-node Bekn network. The urls shown here are the same as those used in the examples.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
**Use of docker and reference implementations**
|
||||||
|
Docker compose and docker are extensively used in the installation and running of the various component software. Similarly the Beckn-ONIX installer, itself being a reference implementation, installs the reference implentation of the Beckn Adapter for the BAP and BPP, reference implementation of the registry and gateway. In order to interact with the internals of these components, we will need to enter the container. Familiarity with Docker will be useful in working with the installation. To list the running containers use `docker ps`. Similarly for example to connect to a container and browse it using shell, use `docker exec -it bap-client sh`
|
||||||
|
|
||||||
|
### Overall Pre-requisites
|
||||||
|
|
||||||
|
- Atleast four virtual servers (EC2 instances) configured on the cloud provider with administrator login (e.g. ssh access) to them.
|
||||||
|
- Access to domain name management with ability to create domain-name/subdomains for each of the components.
|
||||||
|
- Each of the various sections below list additional pre-requisites which build on these.
|
||||||
|
|
||||||
|
### Setting up a new network - Registry
|
||||||
|
|
||||||
|
In the Beckn ecosystem, a new network starts with the setting up of the Registry. All network participant register with the Registry with their public key. They also call the lookup endpoint on the Registry to discover and validate other network participants.
|
||||||
|
|
||||||
|
**Prerequisites for installation**
|
||||||
|
|
||||||
|
- A domain or subdomain where the registry will be accessible (e.g https://onix-registry.becknprotocol.io)
|
||||||
|
- A virtual server with domain/subdomain pointing to it. Refer [Appendix A](#appendix-a---registering-or-adding-domain-or-subdomains) for details
|
||||||
|
- SSL certificate for the server and configured in Nginx. Refer [Appendix B](#ssl-certificates-configured-in-reverse-proxy)
|
||||||
|
- Reverse proxy configured to route the traffic at the registry url (e.g. onix-registry.becknprotocol.io) to port 3030. Refer [Appendix B](#configuring-nginx-reverse-proxy-using-proxy-pass)
|
||||||
|
|
||||||
|
**Installation Steps**
|
||||||
|
|
||||||
|
- Clone the Beckn ONIX repository (git clone https://github.com/beckn/beckn-onix.git)
|
||||||
|
- Change into the installation folder `cd beckn-onix/install`
|
||||||
|
- Run the installation script `./beckn-onix.sh`
|
||||||
|
- Specify you want to start a new network and install the registry
|
||||||
|
- Skip the network configuration download option
|
||||||
|
- Enter the publicly accessible address of the registry (e.g. https://onix-registry.becknprotocol.io)
|
||||||
|
- The registry installation will continue to completion.
|
||||||
|
|
||||||
|
### Setting up a Gateway
|
||||||
|
|
||||||
|
In the Beckn ecosystem, the role of the Gateway is limited to the discovery phase. When the BAP wants to search for an item, it sends it to the Gateway and the Gateway broadcasts the request to all BPPs registered for the domain. It registers itself with the registry upon installation.
|
||||||
|
|
||||||
|
**Prerequisites**
|
||||||
|
|
||||||
|
- Address of the registry of the network the gateway will join (e.g. https://onix-registry.becknprotocol.io)
|
||||||
|
- A domain or subdomain where the gateway will be accessible (e.g https://onix-gateway.becknprotocol.io)
|
||||||
|
- A virtual server with domain/subdomain pointing to it. Refer [Appendix A](#appendix-a---registering-or-adding-domain-or-subdomains) for details
|
||||||
|
- SSL certificate for the server and configured in Nginx. Refer [Appendix B](#ssl-certificates-configured-in-reverse-proxy)
|
||||||
|
- Reverse proxy configured to route the traffic at the gateway url (e.g. onix-gateway.becknprotocol.io) to port 4030. Refer [Appendix B](#configuring-nginx-reverse-proxy-using-proxy-pass)
|
||||||
|
|
||||||
|
**Installation Steps**
|
||||||
|
|
||||||
|
- Clone the Beckn ONIX repository (git clone https://github.com/beckn/beckn-onix.git)
|
||||||
|
- Change into the installation folder `cd beckn-onix/install`
|
||||||
|
- Run the installation script `./beckn-onix.sh`
|
||||||
|
- Specify you want to join an existing network and install the gateway
|
||||||
|
- Skip the network configuration download option
|
||||||
|
- Enter the address of the registry of the network you want to join (e.g. https://onix-registry.becknprotocol.io)
|
||||||
|
- Enter the publicly accessible address of the gateway (e.g. https://onix-gateway.becknprotocol.io)
|
||||||
|
- The gateway installation will continue to completion and it will register itself with the registry as a participant with role BG(Beckn Gateway)
|
||||||
|
|
||||||
|
### Setting up a BAP Beckn Adapter
|
||||||
|
|
||||||
|
The BAP (Beckn Application Platform) is the bridge between buyer side applications and the Beckn Network. As part of Beckn-ONIX installation, a reference implementation of the Beckn Adapter for the BAP is installed. This adapter talks to two logical entities. On the one side you have the buyer applications which call the BAP with Beckn requests. The BAP forwards these requests to the Beckn network and other participants call back the BAP with responses. These two endpoints are referred to as client and network endpoints in this document.
|
||||||
|
|
||||||
|
**Prerequisites**
|
||||||
|
|
||||||
|
- Address of the registry's subscription endpoint of the network the BAP will join (e.g. https://onix-registry.becknprotocol.io/subscribers)
|
||||||
|
- A domain or subdomain where the client endpoint of BAP will be accessible (e.g https://onix-bap-client.becknprotocol.io)
|
||||||
|
- A domain or subdomain where the network endpoint of BAP will be accessible (e.g. https://onix-bap.becknprtocol.io)
|
||||||
|
- A virtual server with both the above domains/subdomains pointing to it. Refer [Appendix A](#appendix-a---registering-or-adding-domain-or-subdomains) for details
|
||||||
|
- SSL certificate for the two endpoints and configured in Nginx. Refer [Appendix B](#ssl-certificates-configured-in-reverse-proxy)
|
||||||
|
- Reverse proxy configured to route the traffic at the bap client url (e.g. onix-bap-client.becknprotocol.io) to port 5001. Refer [Appendix B](#configuring-nginx-reverse-proxy-using-proxy-pass)
|
||||||
|
- Reverse proxy configured to route the traffic at the bap network url (e.g. onix-bap.becknprotocol.io) to port 5002. Refer [Appendix B](#configuring-nginx-reverse-proxy-using-proxy-pass)
|
||||||
|
|
||||||
|
**Installation Steps**
|
||||||
|
|
||||||
|
- Clone the Beckn ONIX repository (git clone https://github.com/beckn/beckn-onix.git)
|
||||||
|
- Change into the installation folder `cd beckn-onix/install`
|
||||||
|
- Run the installation script `./beckn-onix.sh`
|
||||||
|
- Specify you want to join an existing network and install the BAP.
|
||||||
|
- Skip the network configuration download option
|
||||||
|
- Enter the Subscriber id for the BAP. When setting up a new network, its value can be anything you want. However it is recommended to have it the same as the BAP URL without the https:// part (e.g. onix-bap.becknprotocol.io). In existing networks this might be further validated for uniqueness by the registry.
|
||||||
|
- Enter the Subscriber URI for the BAP. This is the network endpoint of the BAP Beckn Adapter. (e.g. https://onix-bap.becknprotocol.io)
|
||||||
|
- Enter the address of the subscription endpoint of the registry of the network you want to join (e.g. https://onix-registry.becknprotocol.io/subscribers). Note the suffix subscribers in the endpoint address.
|
||||||
|
- The BAP installation will continue to completion and it will register itself with the registry as a network participant.
|
||||||
|
|
||||||
|
### Setting up a BPP Beckn Adapter
|
||||||
|
|
||||||
|
The BPP (Beckn Provider Platform) is the bridge between the seller side applications such as a market place or a headless shop and the Beckn network. As part of Beckn-ONIX installation, a reference implementation of the Beckn Adapter for the BPP is installed. This adapter talks to two entities. On the one side, it talks to the seller side apps. It forwards the requests from the Beckn network to this/these software. It also recieves the responses from the seller side apps. This interface towards the seller side applications is called as BPP-Client (client within the context of BPP)within this document. The BPP adapter also receives requests from the Beckn network and returns back the responses to the requesting participant. This part of the Beckn Adapter is called the BPP Network (or just network when the BPP context is implied.)
|
||||||
|
|
||||||
|
**Prerequisites**
|
||||||
|
|
||||||
|
- Address of the registry's subscription endpoint of the network the BPP will join (e.g. https://onix-registry.becknprotocol.io/subscribers)
|
||||||
|
- A domain or subdomain where the client endpoint of BPP will be accessible (e.g https://onix-bpp-client.becknprotocol.io)
|
||||||
|
- A domain or subdomain where the network endpoint of BPP will be accessible (e.g. https://onix-bap.becknprtocol.io)
|
||||||
|
- A virtual server with both the above domains/subdomains pointing to it. Refer [Appendix A](#appendix-a---registering-or-adding-domain-or-subdomains) for details
|
||||||
|
- SSL certificate for the two endpoints and configured in Nginx. Refer [Appendix B](#ssl-certificates-configured-in-reverse-proxy)
|
||||||
|
- Reverse proxy configured to route the traffic at the bap client url (e.g. onix-bap-client.becknprotocol.io) to port 5001. Refer [Appendix B](#configuring-nginx-reverse-proxy-using-proxy-pass)
|
||||||
|
- Reverse proxy configured to route the traffic at the bap network url (e.g. onix-bap.becknprotocol.io) to port 5002. Refer [Appendix B](#configuring-nginx-reverse-proxy-using-proxy-pass)
|
||||||
|
|
||||||
|
**Installation Steps**
|
||||||
|
|
||||||
|
- Clone the Beckn ONIX repository (git clone https://github.com/beckn/beckn-onix.git)
|
||||||
|
- Change into the installation folder `cd beckn-onix/install`
|
||||||
|
- Run the installation script `./beckn-onix.sh`
|
||||||
|
- Specify you want to join an existing network and install the BPP.
|
||||||
|
- Skip the network configuration download option
|
||||||
|
- Enter the Subscriber id for the BPP. When setting up a new network, its value can be anything you want. However it is recommended to have it the same as the BAP URL without the https:// part (e.g. onix-bpp.becknprotocol.io). In existing networks this might be further validated for uniqueness by the registry.
|
||||||
|
- Enter the Subscriber URL for the BPP (e.g. https://onix-bpp.becknprotocol.io). This is the network endpoint of the BPP Beckn Adapter.
|
||||||
|
- Enter the webhook URL. This is the endpoint on your custom market place or headless shop which will receive Beckn requests. The endpoint usually contains the address of the market place or shop as a substring. (e.g. https://unified-bpp.becknprotocol.io)
|
||||||
|
- Enter the address of the subscription endpoint of the registry of the network you want to join (e.g. https://onix-registry.becknprotocol.io/subscribers). Note the suffix subscribers in the endpoint address.
|
||||||
|
- The BPP installation will continue to completion and it will register itself with the registry as a network participant.
|
||||||
|
|
||||||
|
### Changing subscription status of BAP and BPP at the registry
|
||||||
|
|
||||||
|
While the Beckn ONIX installs network participant software as well as registers them with the Registry, they need to be manually put to the 'Subscribed' status. Its only then that they can transact. In real networks, the network facilitator might require additional documentation or validation before transitioning the BAP/BPP to the Subscribed state. When we are setting up the entire network ourselves, we can also do this task.
|
||||||
|
|
||||||
|
**Steps**
|
||||||
|
|
||||||
|
- Log into your registry at the url you specified (e.g. https://onix-registry.becknprotocol.io). The default username, password is root/root
|
||||||
|
- Select Network Participants Under Admin menu
|
||||||
|
- Edit the BAP record. In the Network Role tab, edit the entry and change the state to 'Subscribed'
|
||||||
|
- Repeat the same for the BPP record.
|
||||||
|
|
||||||
|
### Downloading Layer 2 Configuration for a domain
|
||||||
|
|
||||||
|
With Beckn onix installation of the Beckn network, we have a core network with all required network participants. However we cannot still do any transactions on this network. In order to do transactions, we need the Layer 2 Config file for the domain in which we want to transact. Layer 2 configuration files contain
|
||||||
|
|
||||||
|
- rules and policies agreed upon by entities operating in the domain through working group and other consultations
|
||||||
|
- rules and policies required by the network facilitator
|
||||||
|
|
||||||
|
Currently the layer-2 config are per domain, though this might change with future evolution of the core specification. The layer 2 config file is usually hosted by the network facilitator. Participants have to get this from the hosted location and install it within the respective containers. This is currently done by a script that needs to be run and provided with address of the layer 2 config file.
|
||||||
|
|
||||||
|
**Steps**
|
||||||
|
|
||||||
|
- Change into the beckn-onix/layer2 folder.
|
||||||
|
- Start the `download_layer_2_config_bap.sh`
|
||||||
|
- Specify the path of the layer 2 config file for the required domain. (e.g. https://raw.githubusercontent.com/beckn/beckn-onix/main/layer2/samples/retail_1.1.0.yaml). Some sample layer 2 config files are present at `https://raw.githubusercontent.com/beckn/beckn-onix/main/layer2/samples/retail_1.1.0.yaml`
|
||||||
|
- This file is downloaded and installed into the container.
|
||||||
|
- Repeat the same process for the BPP. However run the `download_layer_2_config_bpp.sh` file instead.
|
||||||
|
|
||||||
|
### Testing transactions on the new network
|
||||||
|
|
||||||
|
- We can use postman collection for the specific domain to test end to end communication on the domain. Some sample postman collections for testing are [present here](https://github.com/beckn/beckn-sandbox/tree/main/artefacts)
|
||||||
|
- When running postman collection from the buyer side, the base url to which the requests are sent should be the client side endpoint of the BAP Beckn Adapter instance. (e.g https://onix-bap-client.becknprotocol.io)
|
||||||
|
|
||||||
|
## Running Beckn ONIX locally
|
||||||
|
|
||||||
|
- In order for people new to Beckn who want to try out Beckn on their own machine, a simple one click installer has been written. Currently it can be installed by running the `start_beckn.sh` script. In the next release, this will be integrated with the main script and this script deprecated. An all in one installation has preconfigured values for variables and so pretty much does not ask for any input.
|
||||||
|
|
||||||
|
## Appendix A - Registering or adding domain or subdomains
|
||||||
|
|
||||||
|
All the components of Beckn network need to be publicly accessible. Using domain names for them is the easiest. There are two options for domain names. One is a separate domain name for each component(e.g. registrybp.io). Second is to use subdomains for the individual componetns (e.g. onix-registry.becknprotocol.io , onix-gateway.becknprotocol.io etc). Which one of these two are used depends on the business requirement. For example if an organization is the network facilitator, they might go for a domain name for the registry instead of subdomain. In the examples given above we have primarily used subdomain approach.
|
||||||
|
|
||||||
|
The process of registering domain names differs by the Domain Registrar. An example is here https://www.cloudflare.com/en-gb/products/registrar/
|
||||||
|
|
||||||
|
Similarly the process of adding subdomains differs by the Domain Registrar. An example is here https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-subdomain/
|
||||||
|
|
||||||
|
For example in the prerequesites when it says "Subdomain name added(e.g. onix-gateway.becknprotocol.io) and point to this virtual server", what needs to be done is
|
||||||
|
|
||||||
|
- Decide on a name (here it is onix-gateway)
|
||||||
|
- Add the name as subdomain at your registrar (here the registrar would be that of becknnprotocol.io)
|
||||||
|
- Point the record at the registrar to the machine on which you are installing the gateway
|
||||||
|
|
||||||
|
## Appendix B - NGINX reverse proxy configuration
|
||||||
|
|
||||||
|
All components of Beckn network need to be publicly accessible. Also it is required that they run on the https server for additional security. In addition some of the components of the reference implementation have two webservers running on the same node and require to be each publicly accessible through https. In order to achieve all of these requirements, it is recommended to install reverse-proxy on all the machines where the Beckn network components installed. This document uses Nginx as Reverse proxy, but the same can be configured through other programs.
|
||||||
|
|
||||||
|
### SSL certificates configured in reverse proxy
|
||||||
|
|
||||||
|
To enable https communication, SSL certificates need to be obtained and configured in Nginx. Depending on where you get the SSL certificate from, the process will vary. One such process for a provider [letsencrypt is documented here](https://letsencrypt.org/getting-started/)
|
||||||
|
|
||||||
|
Once the SSL certificate is obtained, it needs to be configured. For Nginx, this [configuration is explained here] (https://nginx.org/en/docs/http/configuring_https_servers.html)
|
||||||
|
|
||||||
|
When the prerequisite in this document says: "Nginx is configured with ssl certificate for the registry URL(e.g. https://onix-registry.becknprotocol.io)", it involves the following:
|
||||||
|
|
||||||
|
- Obtain ssl certificate for `https://onix-registry.becknprotocol.io`
|
||||||
|
- Configure Nginx on the virtual server to create a server at https://onix-registry.becknprotocol.io.
|
||||||
|
- Configure this server to use the ssl certificate
|
||||||
|
|
||||||
|
### Configuring Nginx reverse proxy using proxy pass
|
||||||
|
|
||||||
|
In the role of reverse proxy, Nginx will forward communication that came on a particular url to a different destination (usually a server running on the same machine at a different port). This facility is used extensively in the reference Beckn components. For example the reference implementation of the BAP Protocol Server installs two servers. One at port 5001 and another at port 5002. We will need to configure two URLs (e.g. https://onix-bap-client.becknprotocol.io and https://onix-bap.becknprotocol.io) for this virtual server and Nginx should forward the first to server running on port 5001 and second to server running on port 5002.
|
||||||
|
|
||||||
|
[This document](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/) explains the configuration of reverse proxy using proxy_pass
|
||||||
|
|
||||||
|
You can find sample Nginx configuration for the Registry, Gateway, BAP and BPP [here](./sample_nginx_configuration.md)
|
||||||
Reference in New Issue
Block a user