This repository provides a step-by-step guide to set up an OpenAirInterface (OAI) TestBed with extended xApp capabilities.
It covers deployment and integration of the following components:
- Core Network
- FlexRIC
- gNB
- NR UE
- xApp KPM Monitoring
- xApp DRB Management
- xApp Admission Control (AD)
The goal of this project is to enhance the standard OAI xApps by introducing new features, persistence, and advanced functionalities.
These improvements allow for better observability, resource management, and control of the OAI 5G system.
All RAN components (FlexRIC, gNB, and UE) along with the xApps have been fully dockerized to ensure compatibility, portability, and ease of use.
- Persistent KPI storage: Store all KPI metrics in a MySQL database for long-term availability and analysis.
- Extended metrics support: In addition to default metrics, collect advanced metrics such as:
RRU RSRPCSI MCSPUSCH SNR- ... and more.
-
DRB Management xApp
- Dynamically manage Data Radio Bearers (DRBs) to optimize throughput and reliability.
-
Admission Control (AD) xApp
- Smart admission policies for handling UE connections.
- Helps control resource allocation and maintain network QoS.
- Deployment guides for Core Network and FlexRIC.
- Source code and documentation for:
- gNB and NR UE
- KPM Monitoring xApp
- DRB Management xApp
- Admission Control xApp
Before you begin setting up the environment, make sure you have the following:
- Docker & Docker Compose installed and running
- Git installed for cloning repositories
- Adequate system resources (CPU, RAM, and Storage) to run multiple containers
Clone the official OAI workshop repository, which provides prebuilt Docker Compose files for deploying the Core Network:
git clone https://gitlab.eurecom.fr/oai/trainings/oai-workshops.gitThis repository includes ready-to-use configurations for OAI’s 5G Core components, making it easier to spin up the core services quickly.
Before deploying, each component must be packaged as a Docker image.
No build is required for the Core Network.
Prebuilt images are available on Docker Hub and are already referenced in the provided Docker Compose file.
To build the FlexRIC Docker image, run the following command:
cd flexric-xapp
docker build -t oai/flexric:v1 -f docker-dev/flexric/Dockerfile.flexric.v1 .Build the gNB image with the QoE-E2 enhancements:
cd gnb-ue
docker build -t oai/gnb-qoe-e2:v1 -f docker-dev/Dockerfile.gnb_qoe_e2.v1 .Build the NR UE image using the same directory as the gNB:
cd gnb-ue
docker build -t oai/nr-ue:v1 -f docker-dev/Dockerfile.nr_ue.v1 .This xApp collects KPM data and pushes it to a MySQL database.
cd flexric-xapp
docker build -t oai/xapp-kpm-mon-qoe-e2:v1 -f docker-dev/xapp_kpm_mon_qoe_e2/Dockerfile.xapp_kpm_mon_qoe_e2.v1 .This xApp provides control over DRBs for QoE-aware policies.
cd flexric-xapp
docker build -t oai/xapp-drb-mng:v1 -f docker-dev/xapp_drb_mng/Dockerfile.xapp_drb_mng.v1 .This xApp handles admission decisions based on network conditions.
cd flexric-xapp
docker build -t oai/xapp-ad:v1 -f docker-dev/xapp_ad/Dockerfile.xapp_ad.v1 .To launch the system, execute the following commands in order:
Start the 5G Core Network using Docker Compose:
cd oai-workshops/cn/
docker compose up -dRun the RIC platform to support E2SM interfaces with the gNB and xApps:
docker run --rm --network host --name oai-flexric oai/flexric:v1Start the gNB container with RAN configs mounted from local directory:
cd gnb-ue/docker-dev/
docker run --rm --privileged --network host \
-v ./gnb_qoe_e2_ran_config:/oai/ran/config \
--name oai-gnb-qoe-e2 oai/gnb-qoe-e2:v1Launch the simulated UE in RFSim mode with appropriate parameters:
cd gnb-ue/docker-dev/
docker run --rm --privileged --network host \
-v ./nr_ue_ran_config:/oai/ran/config \
--name oai-nr-ue \
--entrypoint ./nr-uesoftmodem \
oai/nr-ue:v1 \
-r 106 \
--numerology 1 \
--band 78 \
--ssb 516 \
-C 3619200000 \
--uicc0.imsi 001010000000101 \
--rfsim \
-O /oai/ran/config/ue.confStart the MySQL database required by the KPM xApp, then run the xApp:
cd flexric-xapp/docker-dev/mysql_database/
docker compose up -d
docker run --rm --network host --name xapp-kpm-mon-qoe-e2 oai/xapp-kpm-mon-qoe-e2:v1Run the DRB management xApp which exposes a control interface on port 8080:
docker run --rm --network host --name xapp-drb-mng -p 8080:8080 oai/xapp-drb-mng:v1Run the Admission Control xApp which makes policy decisions for UE admission:
docker run --rm --network host --name xapp-ad oai/xapp-ad:v1 --run_count 3You can specify the run_count argument during the docker run stage.
This parameter controls how many times the main code will loop.
A docker-compose.yml file is provided to simplify the deployment of all RAN and xApp components.
This avoids the need to manually run each service using docker run.
You can customize the command section and the mounted configuration files of each service in the compose file to apply different configurations.
After the core network components are up and running, start the services with:
cd flexric-xapp/docker-dev/testbed_qoe_e2
docker compose up -dTo view the output of a specific container, run:
docker logs <container-name>Replace container-name with the actual container name (e.g., oai-flexric, oai-nr-ue, or oai-xapp-drb-mng).
A set of health checks is included to verify that all services are up and running. This ensures the environment is correctly initialized before you proceed with further testing.
This section provides example outputs from a complete run of the testbed. These snapshots illustrate the functionality of different components, including container orchestration, log monitoring, and persistent metric storage.
The following snapshot shows all active containers deployed in the testbed.
The logs below highlight real-time interactions between the gNB and the Admission Control (AD) xApp.
The testbed persists collected Key Performance Metrics (KPMs) into a MySQL database for post-analysis and visualization. This snapshot shows a sample database table where metrics are stored.
