BAP - Installing Protocol Server
UBA UBA NETWORK - GUIDE FOR INSTALLING PROTOCOL SERVER (BAP)
Installation of Beckn Protocol Adapter using BecknOnix Version 1.0 Once you have gone through all the information and documentation and have enough clarity, the next step is to install and set up the Beckn Protocol server. The installation and setup of Beckn Protocol server using Beckn-Onix is the suggested/recommended way before you can transact over the network
Onboarding using a use case scenario (an Example Usecase)
The organization - FinAidIndia wants to onboard the UBI network as a Financial/Scholarship seeker. By onboarding on to the UBI Network they can discover all the services available in the network.
The onboarding process includes
reading and understanding the documentation for the understanding of the specs,apis etc..
Preparing infrastructure and other prerequisites
Registering on to the UBI Sandbox
Installing the Beckn Onix
Setting up Webhook
Creating the provider modules to host the Beckn endpoint and accept and process incoming requests and send back the responses
1. PRE-REQUISITES
1
Virtual Servers
Provision cloud instances (e.g., AWS EC2).
Ensure you have SSH administrator access. Configuration:
2 VCPS, 4GB RAM (minimum), 50GB Minimum
2
Operating System
Supported and Tested OS:
Ubuntu 20.04 / 22.04 /24.04
Debian 12
Amazon Linux 2
3
Docker
Latest Docker version Recommended. Minimum Version 18
4
Domain
For the Seeker Platform (BAP) FinAidIndia, you’ll need two domains (or subdomains):
Client Endpoint (BAP Client)
This is where your internal client application connects.
Example:
https://finaidindia-bap-client.org
Network Endpoint (BAP Network)
This is the public-facing endpoint through which your protocol server connects to the Beckn Network(registry/gateway)
Example:
https://finaidindia-bap-network.org
IMP. Both domains must be publicly accessible, have SSL certificates, and be configured with NGINX reverse proxy.
5
SSL Certificates
Every Beckn endpoint must be secured with HTTPS. Obtain valid SSL certificates for your chosen domains (e.g., from Let’s Encrypt or your CA) and install them on the server.
6
NGINX Reverse Proxy
Use Nginx as a reverse proxy to route incoming HTTPS requests from the Beckn network to your BPP adapter or webhook service.
(In most cases, your DevOps team will handle this configuration.)
2. SELF-REGISTERING ON TO THE UBI REGISTRY
Before you can install and configure your BAP (Seeker Platform) with Beckn Onix, you must register yourself in the UBI Sandbox Registry.
This step is mandatory because the username and password you create here will be required during the installation process.
🔑 Steps to Register
Open the UBI Sandbox Registry portal:
👉
https://registry-sandbox.the-ubi.io/
On the login page, click “I am a New User”. Enter a Username and Password of your choice, then complete the registration.
⚠️ Important Note
✅ Make sure to note down these credentials safely – you’ll need them later when running the installation
You can verify the registration by logging into the registry using this newly created username and password
3. BAP - INSTALLATION OF BPP Protocol server using BecknOnix
After completing the prerequisites and self-registering in the registry, the next step is to set up the BAP Protocol Server.
The BAP Protocol Server acts as the bridge between your seeker application (e.g., FinAidIndia) and the Beckn network.
It:
Sends requests such as search, select, confirm, etc. into the network
Receives responses like on_search, on_select, on_confirm directly into the BAP client container
With Beckn Onix v1.0, the installation is straightforward thanks to the installer script.
⚠️ Important Note
✅ Make sure you have completed all the steps in the Prerequisites section before starting installation.
🔄 Beckn Onix has a newer version with a completely different architecture. Since that release is still under evaluation, this guide covers Beckn Onix v1.0 only.
📥 Clone the Repository (Specific Branch)
Clone Beckn Onix v1.0
git clone https://github.com/Beckn-One/beckn-onix.git
#Move into the repo folder
cd beckn-onix
# Switch to the desired branch
git checkout fix/beckn-onix-typo
Run the Installation Script
# Go to the install folder
cd install
./beckn-onix.sh
You’ll be prompted for several inputs.
Select “1” for as you want to join an existing network (UBI in this case) and press Enter
Please select a Participant Type. Since you are a provider , select BAP in this case) and press Enter
Enter Subscriber ID (Enter the Subscriber Id. Generally this will be your URL without http. ) And Subscriber URL - this will be the network URL. (Please refer to the pre-requisite section if required for details)
Enter the Registry URL as shown below. The registry url for UBI is https://registry-sandbox.the-ubi.io/subscribers
Registry Username/Password Note: Use the same credentials you created during self-registration.
⚠️ Note: If prompted for “select a domain” or “install layer2 config”, simply skip/ignore and continue.
Now, this will start installing the protocol server and various dependencies
Once Done you will see a BAP installation Successful Message as shown in the below log
Verify the Installation You can verify the installation by using the docker command. You should see services like bap-network, bap-client, etc.
docker ps -a
Verify Registry You can also verify that there is an entry for your domain that is created in the registry with keys etc.. by login in to the registry using the username and password created
Activate your entry in the Registry by changing the status from “INITIATED” to “SUBSCRIBED”. Pls follow the steps below for the same Edit your entry in registry Select “Network Role” Click on the pencil to edit
Activate your entry in the Registry by changing the status from “INITIATED” to “SUBSCRIBED”.
Edit the “Network Domain” and select “UBI Financial Support” as the domain and Save the changes
Protocol Server Installed Successfully !
With the above steps, you have now successfully installed the BPP Protocol Server for FinAidIndia.
By default: BAP Client will be running on port 5001 BAP Network will be running on port 5002 You can verify that the containers are running using:
docker ps
4. Nginx Configuration (with SSL)
As part of the prerequisites, you should already have configured Nginx for both: The Client domain → https://finaidindia-bap-client.org The Network domain → https://finaidindia-bap-network.org
Your SSL certificates should also be attached to these domains.
Below is a sample Nginx configuration (before SSL blocks are added) for your reference. This can change as per your network settings/requirements
Client Config (Port 5001)
server { listen 80; server_name finaidindia-bap-client.org;
location / { proxy_pass http://127.0.0.1:5001; # BAP client backend proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }
Network Config (Port 5002)
server { listen 80; listen [::]:80; server_name finaidindia-bap-network.org;
location / { resolver 1.1.1.1 ipv6=off; proxy_pass http://127.0.0.1:5002/; client_max_body_size 30m; proxy_read_timeout 700s; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header Connection ""; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_buffer_size 128k; proxy_buffers 4 256k; proxy_busy_buffers_size 256k; proxy_headers_hash_max_size 1024; proxy_headers_hash_bucket_size 512; } }
Testing Your Setup
Once you add your SSL certificate, these blocks will be updated with
listen 443 ssl;
and the certificate paths (ssl_certificate and ssl_certificate_key).
To Test
After finishing Nginx and SSL configuration, test that your services are running correctly:
# Test the local ports
curl http://localhost:5001
curl http://localhost:5002
# Test via your domains (with SSL enabled)
curl -k https://finaidindia-bap-client.org
curl -k https://finaidindia-bap-network.org
If you see a response (even an empty JSON), your BPP Protocol Server and Nginx setup are working correctly.
5. Enabling Layer 2 Config in Beckn
In the Beckn ecosystem, the Layer 2 config allows network specific schema customization in case required. Basically It allows you to extend the base schema with network-specific configurations.
The Layer 2 config must be present in the schemas/ folder of both the client and network containers of your protocol server (BAP or BPP).
The filename should match the domain name of the network. For example:
Domain → ubi:financial-support
Config file → ubi_financial-support_1.1.0.yaml
Steps to Enable Layer 2 Config
Step 1. Enter the Docker container
Run the following for each container (client and network):
docker exec -it <bap-or-bpp>-<client-or-network> sh
Example for a BAP client:
docker exec -it bap-client sh
Step 2. Go to the schemas folder
cd schemas
Step 3. Copy the Core Schema and Rename Duplicate the base schema file (core_1.1.0.yaml) and rename it to match your network domain.
cp core_1.1.0.yaml ubi_financial-support_1.1.0.yaml
This new file will act as the Layer 2 config, where the network-specific rules can be added.
Step 4. Repeat for All Containers
Do the same in:
bap-client Bap-network (or bpp-client and bpp-network if you’re setting up a BPP).
Step 5. Restart the Containers
Once the Layer 2 config files are created, exit the container and restart both client and network containers one by one:
Example:
Restart the Containers
docker restart bap-client
docker restart bap-network