The oai web server is an optional monitoring and debugging tool. Purpose is to give access to oai softmodems functionalities via a web interface. In this first release interface to the telnet server commands and to the softscope are delivered.
The oai web server is an optional monitoring and debugging tool. Purpose is to give access to oai softmodems functionalities via a web interface. In this release interface to the telnet server commands and to the softscope are delivered.
The web server interface is implemented in two parts: a back-end, included in the softmodem process and a front-end which is a browser application.
The web server interface is implemented in two parts: a back-end, included in the softmodem process and a front-end which is a browser application.
The oai web server back-end is implemented in a shared library to be loaded by the [oai shared library loader](loader) when `--websrv` option is specified on the command line. `libwebsrv.so ` code is common to all oai softmodem executables, the current release has been tested with the nr UE and the gNB.
The oai web server back-end is implemented in a shared library to be loaded by the [oai shared library loader](../../DOC/loader.md) when `--websrv` option is specified on the command line. `libwebsrv.so` code is common to all oai softmodem executables,
the current release has been tested with the nr UE and the gNB.
The front-end is an [angular](https://angular.io/docs) application. After being built and installed it is delivered to browsers by the back-end at connection time.
Front-end and back-end communicate via http request - http response transactions, including `json` body. these `json` interfaces are defined in the [frontend/src/app/api/XXXX.api.ts](https://gitlab.eurecom.fr/oai/openairinterface5g/tree/develop/common/utils/websrv/src/frontend/src/app/api/) files. Back-end decapsulates the http requests it receives, looking for the `json`body to determine the requested information or command. Then the back-end builds a http response, with a `json`body encapsulating the requested information or the requested command result.
Front-end and back-end communicate via http request - http response transactions, including `json` body. these `json` interfaces are defined in the [frontend/src/app/api/XXXX.api.ts](../frontend/src/app/api/) files.
Back-end uses a callback machanism to map received http requests to dedicated functions. Typically a callback function decapsulates the http requests it receives, looking for the `json`body to determine the requested information or command. Then the back-end builds a
http response, with a `json`body encapsulating the requested information or the requested command result.
When unsolicited communication, from back-end to front-end is necessary, a [websocket](https://www.rfc-editor.org/rfc/rfc6455) link is opened. This is the case for the softscope interface.
# web server interface source files
web server source files are located in [common/utils/websrv](https://gitlab.eurecom.fr/oai/openairinterface5g/tree/develop/common/utils/websrv)
web server source files are located in [common/utils/websrv](..)
1. back-end files are directly located in the `websrv` repository
1. The [frontend/src](https://gitlab.eurecom.fr/oai/openairinterface5g/tree/develop/common/utils/websrv/src/frontend) sub-directory contains the angular front-end source tree.
1.[common/utils/websrv/helpfiles](https://gitlab.eurecom.fr/oai/openairinterface5g/tree/develop/common/utils/websrv/helpfiles) contains files delivered to the front-end to respond to help requests.
1. The [frontend/src](../frontend/src) sub-directory contains the angular front-end source tree.
1.[common/utils/websrv/helpfiles](../helpfiles) contains files delivered to the front-end to respond to help requests.
Backend devlopment is classical C programming, using [libulfius](https://github.com/babelouest/ulfius/blob/master/API.md) for the web server implementation
and [libjansson](https://jansson.readthedocs.io/en/latest/) for formatting and accessing the JSON http bodies which are used by the angular frontend to exchange data with the server.
The backend processes the http requests coming from the frontend using the ulfius callback mechanism. backend can also send unsollicited data to the frontend using a websocket
Frontend has been developped using the [angular framework](https://angular.io/) which implies TypeScript and HTML programming with the specificity of the node.js libraries and
angular extensions.
Debugging the frontend side may be more difficult than the backend, some tools may help:
- Some IDE such as [vscode](https://code.visualstudio.com/) are "angular aware" and can ease debugging your modifications .
- Setting UTIL log level to informational in the backend and websrv debug flag to 2 ( `--log_config.util_log_level info --websrv.debug 2` ) will trigger backend traces which may help, including the dump of JSON type http content
- Browser devloper tools such as console may also help
There is a dedicated CMakeLists.txt, located in the websrv directory, to build both backend and frontend. Including the websrv option when configuring cmake ( `./build_oai --build-lib websrv` ) is required to be able to include the web server targets in the oai build scripts (either Makefile or ninja).
`libwebsrv.so` shared library is the backend binary. It is possibly dynamically loaded at runtime, which then triggers the execution of the
`websrv_autoinit` function that initializes the http server. Re-building the backend can be done using either `make websrv` or `ninja websrv` and it also re-builds the frontend .
The frontend run-time is made of a set of files generated from the TypeScript, HTML, CSS sources via the npm utility. It also includes some directly edited files such as the helpfiles. Frontend run-time is installed in the `websrv` sub-directory of the build path
(usually `<oai repository>/cmake_targets/ran_build/build`) Re-building frontend can be done via the websrvfront target: `make websrvfront` or `ninja websrvfront`.
###### backend source files
They are all located in the websrv repository
| source file |description |
|---|---|
| websrv.c | main backend file, starts the http server and contains functions for telnet server interface ( softmodem commands tab) |
| websrv.h | the only web server include file, contains utils prototypes, constants definitions, message definitions. Note that it must be kept consistent with frontend, unfortunatly we have not found a way to have common include files between C and javascript |
| websrv_utils.c | utility functions common to all backend sources: dump http request and JSON content. format string response from a file, a C string, a buffer asynchronously loaded. format help from help file |
| websrv_websockets.c | contains functions for the softscope interface (scope tab): initialize, close websocket, dispatch incoming messages, send a websocket message to frontend |
| websrv_scope.c | softscope specific functions: callbacks to process softope frontend request and function to send, receive and process softscope websocket messages |
| websrv_noforms.c websrv_noforms.h | stub functions to help using a common softscope interface for xforms softscope and the webserver softscope, could be removed when improving softscope architecture (don't use interface specific function in nr_physcope.c) |
###### main frontend source files
Frontend directory tree comes from the angular framework. The root of this tree is `websrv/frontend/`. Main sub directories or files are:
-`src/app/api` contains TypeScript files with functions to send http requests to the backend. These functions are used from components sources.
-`src/app/components/<component name>` contains the code (TypeScript, HTML and possibly CSS or XCSS) for a web page, for example the softscope, or popup page used to ask a question or return transaction status.
-`src/app/components/controls` contains TypeScript code used for managing some form fields used in the `softmodem commands` tab.
-`src/app/components/services` contain TypeScript code for utilities such as managing the websocket interface with the backend or downloading a file.
-`src/app/app-routing-module.ts` defines mapping between urls as entered by user and components
-`src/app/app.component.ts``src/app/app.component.html` define the first page displayed to user
-`src/environments` contains environment.<buildtype>.ts file wich defines the `environment` variable depending on the build type. The delivered build scripts are using the `prod` version which has been written to make frontend and backend to interact properly in a production platform. Other build type is to be used in debug environment where frontend is not downloaded from the backend.
-`src/commondefs.ts`: constant definitions common to several TypeScript sources
back-end and front-end are both built when the build of the `websrv` optional library is requested. When cmake configuration has been completed, with websrv enabled,font-end and back-end can be built separatly, using respectively `make frontend` or `make websrv` from the build repository.
## building the webserver
When all dependencies are met, you can build the web server interface components using the build_oai script with the `--build-lib all` option . As the web interface is an optional component, if it's dependencies are not found it won't stop the build. Web interface components (back-end or front-end) which cannot be built are just skipped. If you specifically ask for the webserver build ( `--build-lib websrv`) the build will fail if dependencies check failed.
###### build example when missing dependencies
back-end (the http server) and front-end (the html and javascript code for the browsers) are both built when the build of the `websrv` optional library is requested.
You can include the web server interface components in your build using the build_oai script with the `--build-lib "telnetsrv websrv"` option.
The related cmake cache entry in `ran_build/build/CMakeCache.txt` for building the web server
is `ENABLE_WEBSRV:BOOL=ON`
When cmake configuration has been completed, with websrv enabled and all dependencies met,font-end and back-end
can be built separately, using respectively `make websrvfront` or `make websrv` from the build repository (replace make by ninja if you
build using ninja).
###### build example when back-end dependency is not installed
To prevent difficult situations with nodejs or npm versions it is better to specifically install the required nodejs version (after removing existing versions of npm and nodejs), as explained
[here](https://www.stewright.me/2023/04/install-nodejs-18-on-ubuntu-22-04/) for ubuntu. Similar instructions can be found for other distributions.
It is also possible to make several nodejs versions co-habiting on your system, this is beyond this doc.
Before building the front-end you need to install the npm node.js installer, otherwise the make target won't exist:
```
`apt-get install npm` for ubuntu or `dnf install npm`for fedora
###### building and installing the front-end after cmake has been successfully configured
then configure cmake to be able to build and install the frontend without using the build_oai script:
``` bash
```
cd \<oai repository\>/openairinterface5g/cmake_targets/ran_build/build
make websrvfront
up to date, audited 1099 packages in 3s
...
...
@@ -135,29 +332,21 @@ Built target websrvfront
```
# Building and installing the web server back-end after cmake has been configured
The back-end has two dependencies:
1. the [ulfius library](https://github.com/babelouest/ulfius) and the corresponding include files which are provided by the ubuntu libulfius-dev package: `sudo apt-get install -y libulfius-dev`
2. the [jansson](https://github.com/akheron/jansson-debian) library and the corresponding include files which are provided by the ubuntu libjansson-dev package: `sudo apt-get install -y libjansson-dev`
Dependencies can also be installed on fedora distribution, the jansson package is `jansson-devel`, ulfius has to be installed as explained [here](https://github.com/babelouest/ulfius/blob/master/INSTALL.md#pre-compiled-packages).
The websrv targets won't be available till cmake has been successfully configured with the websrv option enabled
###### building and installing the back-end after cmake has been successfully configured
This will create the `libwebsrv.so` file in the `targets/bin` and `cmake_targets/ran_build/build` sub directories of the oai repository.
When starting the softmodem, you must specify the **_\-\-websrv_** option to load and start the web server. The web server is loaded via the [oai shared library loader](loader).
...
...
@@ -166,7 +355,7 @@ When starting the softmodem, you must specify the **_\-\-websrv_** option to loa
## web server parameters
The web server back-end is using the [oai configuration module](Config/Rtusage). web server parameters must be specified in the websrv section.
The web server back-end is using the [oai configuration module](Config/Rtusage). web server parameters must be specified in the websrv section.
| name | type | default | description |
|:---:|:---:|:---:|:----|
...
...
@@ -180,7 +369,7 @@ The web server back-end is using the [oai configuration module](Config/Rtusage).
## running the back-end
To trigger the back-end use the `--websrv` option, possibly modifying the parameters as explained in the previous chapter. The two following commands allow starting the oai gNB and the oai 5G UE on the same computer, starting the telnet server and the web interface on both executables.
@@ -191,18 +380,20 @@ To trigger the back-end use the `--websrv` option, possibly modifying the parame
Assuming that the previous commands run successfully and that you also run your browser on the same host, you should be able to connect to the gNB and UE web interface using respectively the following url's:
http://127.0.0.1:8090/websrv/index.html
http://127.0.0.1:8092/websrv/index.html
The interface should be intuitive enough, keeping in mind the following restrictions:
- The command tab is not available if the telnet server is not enabled
- The softscope tab is not available if the xforms scope is started `(-d` option)
- The softscope tab is not available if the xforms scope is started (`-d` option)
- Only one connection is supported to a back-end, especially for the scope interface
Some front-end objects, which usage are less intuitive provide a tooltip to help interface usage.
