The Lehr-Lern-Szenario Managment Server (LLS-MS) is an auxiliary component to the main VR app (LLS-VR-Client). It manages the creation and removal of LLS-VR-Server instances (which include the dedicated VR-Rooms), which users of the main LLS-VR-Client Unity app can join.

LLS-MS is concerned with the following tasks:

• Storing the virtual avatars (consisting of one model file and an optional texture file) users can upload via the website /avatar/create.
• Allowing for the avatars to be retrieved by the LLS-VR-Client for using them as personal avatars in a VR-Room (via an access code).
• Providing an interface for instantiating VR-Rooms, meaning the instantiation of LLS-VR-Servers.
• Delivering all necessary information to the LLS-VR-Server that are required for startup (being the access code for the presenter, the access code for the listeners, the name of the VR-Room and urls for the slides).
• Assigning ports from the defined port range to the individual LLS-VR-Server (collision-free).
• Shutting down LLS-VR-Servers in case they do not behave as expected.
• Providing interfaces for the client to query available LLS-VR-Servers (especially their respective names and ports) so they can be presented to the user in the VR environment.
• Generating the access codes for individual LLS-VR-Servers (one for listeners and one for the presenter) and passing them to the LLS-VR-Server.
• Delivering two HTML webpages with forms to upload an avatar (avatar/create) and to create a new VR-Room/LLS-VR-Server (create/room).
• (a possible future feature that is not implemented yet:) Allowing for a centralized authentication.

The identifying access code for virtual avatars (the user types in when trying to enter a VR-Room via the LLS-VR-Client application on a Meta HMD) as well as the access codes for VR-Rooms (the user types in in order to join as a listener or a presenter) are six-digit numerical codes. The user needs to enter these codes while being in the virtual world, not having access to a physical keyboard. This is why short codes were implemented. The server (LLS-MS and LLS-VR-Server) is intended to be protected against brute force via the network setup (e.g. VPN). The network restriction is the only place where access may be limited, the servers themselfs do not have any protection whatsoever.

Running LLS-MS

There are two ways to run this application: you can either use the prebuilt version stored in the repository registry or you build the script files/the image yourself locally. Both yield the same image and outcome and allow you to specify some options via the defined environment variables:

HTTP_SERVER_PORT = 3000 (default)
ROOM_IMAGE_DESIGNATOR = hylec (default)
CONTAINER_PORT_RANGE = 17000,19000 (default)
STARTUP_TIMEOUT = 5000 (default)
BEHAVIOUR_AFTER_FAILED_STARTUP = STOP_AND_REMOVE (default)
AVATAR_PRESERVATION_TIME = 172800000 (default)

You can adjust the STARTUP_TIMEOUT variable (timeout in milliseconds to wait for the server container to report healthy, after which its considered crashed) if you experience startup failures for the LLS-VR-Server container.

The variable BEHAVIOUR_AFTER_FAILED_STARTUP is helpful if you want to diagnose why your LLS-VR-Server container has not started correctly, because in the default configuration (production configuration) it is defined that the failed container is to be stopped and removed from the docker container storage, which also removes the log. This is meant to prevent a resource leak like case, where repeated startup leads to storage exhaustion which in turn could crash the host system when failed container fill up all available storage. Alternate options for this variable are LOG, STOP and STOP_AND_REMOVE.

The ROOM_IMAGE_DESIGNATOR is used to identify the docker image to start for each LLS-VR-Server. It can be changed, e.g., to a development build. The easiest option is to target the image stored in the main repository for this application (see the LLS-VR-Client application repository).

You are able to change the automatic discarding of avatars with the variable AVATAR_PRESERVATION_TIME. It is a timeout in milliseconds to keep an avatar available after the last request to requery it was issued (e.g. a user with this avatar entered a room). After that timeout, it is removed from the server and in time from the clients when they close the application.

Via the prebuilt image

The only prerequisite to start this application is docker. You can fetch the image from the registry of this repository and start it with the following command:

docker run -dit -p 3000:3000 -v /var/run/docker.sock:/var/run/docker.sock gitlab.tu-dortmund.de:5050/ls7/hyleclehrlernszenariocompanionapp:latest

Since this application is meant to handle other containers it requires the docker socket file to be linked into the container so it can issue commands to the docker daemon. The port can freely be changed, but should remain at 3000 to ensure that it can be easily found by the LLS-VR-Client (otherwise you need to change the configuration of the LLS-VR-Client).

Self build

To build this application yourself you need this repository, nodejs, and docker installed and ideally linked in the path. You can either clone this repository (with git) or fetch the .zip file from the page.

# navigate to the directory with the repository contents

# prerequisite: enabling yarn
npm install -g corepack
yarn install

# 1. installing dependencies
yarn

# 2. building bundled application
yarn build

# you can run the application now by issuing
node build/handler.js

# (optional) 3. packaging the script files into a docker image
# either
./build-image
# or
docker build -f Dockerfile -t gitlab.tu-dortmund.de:5050/ls7/hyleclehrlernszenariocompanionapp build

# (optional) 4. running the image
docker run -dit -p 3000:3000 -v /var/run/docker.sock:/var/run/docker.sock gitlab.tu-dortmund.de:5050/ls7/hyleclehrlernszenariocompanionapp:latest

Structure and Technical Details

The LLS-MS is implemented as a nodejs express.js HTTP server, which connects and communicates with a docker instance. It is split into two main modules.

Avatar Module

The first module of the LLS-MS focuses on managing the avatars users should be able to access/use when joining VR-Rooms, and which are supposed to serve as their virtual representations. The module allows users to upload their personal virtual avatar before starting the LLS-VR-Client, and makes them accessible via a code to be typed in when trying to join a VR-Room.

An avatar is an entity consisting of one file, being the 3D model (here a glb file with the 3D triangle mesh forming the volume of the scanned user (from the HyLeC Scanner). Additionally, the interface allows for uploading a texture file, which is a historic feature provided because the previously used fbx format was not able to store model and texture in one file.

The avatar data can be considered biometric data based on article 4(14) of the European GDPR. Therefore, it is data that needs to be handled with extensive security and usage consideration. To mititage most of the storage and query issues, the avatar is not stored to persistent storage

As this app does not include any authentication method, it can not feasibly implement any authorization method, which is in high contrast to the required setup by the GDPR.

This is an open issues and needs to be addressed if this app should be considered to be published to a broader audience. As this is currently not the case, we elected to only protect (read obfuscate) the avatars by not publishing the list of available avatars and making them only addressable by a randomly generated ID with six digits which is transferred only on uploading/successfull registration of the avatar.

If the avatar is not used for more than the time specified in AVATAR_PRESERVATION_TIME (which are 48h per default) it is removed from the server; it is never persisted, so this should be in line with the GDPR. Additionally, the avatar is only retrieved for the explicit usage in representing a user in a VR-Room, there is no additional processing so it should be compliant in this regard as well.

The author of the previous text has no legal expertise and the text should NOT be considered legal advice, any assumption of compliance is only of a layman. Ensure any and all assumptions and implementation when a new usage is considered.

Room Module

The room module is the core feature of the server and fully split from the avatar module. A room is a singular instance (VR-Room) of a server instance of the LLS-VR-Server which can be joined by a LLS-VR-Client.

The initial app (being AvaTalk) was designed to only support one singular room. This initial requirement has changed and Unity is not designed to handle multi domain instances for its Unity RPC feature. This and the diverging requirements lead to the creation of this module.

The main goal is to allow the creation of multiple VR-Rooms by users. The encapsulation and separation is handled by docker.

The LLS-VR-Server instances have no knowledge of docker or its respective workings. The LLS-VR-Server only requires some environment variables for its configuration, which could be provided by a user when running it directly without containerization.

Docker does two central things. First, it implements a health check which allows for the LLS-MS in turn to report when the LLS-VR-Server is ready, and then and only then returning the HTTP request for the creation of the VR-Room. Additionally, it is able to stop and remove non well behaving LLS-VR-Servers to clear up resources (RAM, UDP and TCP Ports). This is crucial since every server needs two new ports (one for Unity RPC and one for the voice component), to allow users to identify the VR-Room and connect to a specific instance. And there could be a case where non functioning instances occupy all defined ports without releasing them and then bringing a LLS-MS Server into an unrecoverable state.

In any case, this port mapping is another feature which is implemented via docker. The LLS-VR-Server has no knowledge of the port change.

One additional feature which is used from docker is its metadata tagging and container instance querying. The LLS-MS has no internal ledger of the VR-Rooms because this would be an additional truth, which could divert from the ground truth, which is the actual list of LLS-VR-Server instances running. To query the available VR-Rooms, it queries docker ls and specifies to only retrieve containers which metadata is tagged with the internal UUID of the LLS-MS server, so it does not interfere if multiple instances of the LLS-MS server are using the same docker instance or a previous instance has started them.

Additionally, the ports, access codes and the names are tagged on the container and retrieved there, once queried by an HTTP request. This removes a whole range of issues which might occur when the internal list and the actual list of instances diverges. Future implementations/enhancements should take into consideration, that some caching would be applicable here to ensure an appropriate scaling.