[full-ci] enhancement: allow ocis to provide custom web applications

[fschade]

Overview

The administrator of the environment is capable of providing custom web applications to the users.
This feature is useful for organizations that have specific web applications that they want to provide to their users.

It's important to note that the feature at the moment is only capable of providing static (js, mjs, e.g.) web applications
and does not support injection of dynamic web applications (custom dynamic backends).

Loading Applications

Loading applications is provided in three ways:

• By loading a web application from a user-provided path, by setting the WEB_APPS_PATH environment variable.
• By loading a web application from the default ocis home directory, e.g. $OCIS_BASE_DATA_PATH/web/apps.
• By embedding a web application into the ocis binary which is a build-time option,
  e.g. ocis_src_path/services/web/apps followed by a build.

The list of available applications is composed of the build in extensions and the custom applications
provided by the administrator, e.g. WEB_APPS_PATH or $OCIS_BASE_DATA_PATH/web/apps.

for example, if ocis contains a build in extension image-viewer-dfx and the administrator provides a custom
application image-viewer-obj in the WEB_APPS_PATH directory,the user will be able to access both applications
from the web ui.

Application Structure

Applications always have to follow a strict structure, which is as follows:

• an application must be a directory
• an application must contain a manifest.json file

everything else is skipped and not considered as an application.

The manifest.json file contain the following fields:

• id - required - the name of the application must be unique across all applications
• entrypoint - required - the entrypoint of the application, e.g. index.js, the path is relative to the parent directory
• config - optional - a list of key-value pairs that are passed to the global web application configuration

Application Configuration

it's important to note that an application manifest should never be changed manually;
if a custom configuration is needed, the administrator should provide the required configuration inside the
$OCIS_BASE_DATA_PATH/config/apps.yaml file.

The apps.yaml file must contain a list of key-value pairs which gets merged with the config field.
For example, if the image-viewer-obj application contains the following configuration:

{
  "id": "image-viewer-obj",
  "entrypoint": "index.js",
  "config": {
    "maxWith": 1280,
    "maxHeight": 1280
  }
}

and the apps.yaml file contains the following configuration:

image-viewer-obj:
  config:
    maxHeight: 640
    maxSize: 512

the final configuration for web will be:

{
  "external_apps": [
    {
      "id": "image-viewer-obj",
      "path": "index.js",
      "config": {
        "maxWith": 1280,
        "maxHeight": 640,
        "maxSize": 512
      }
    }
  ]
}

besides the configuration from the manifest.json file, the apps.yaml file can also contain the following fields:

• disabled - optional - defaults to false - if set to true, the application will not be loaded

The local provided configuration yaml will always override the shipped application manifest configuration.

Fallback Mechanism

Besides the configuration and application registration, there is one further important aspect to now;
in the process of loading the application assets, the system uses a fallback mechanism to load the assets.

This is incredibly useful for cases where just a single asset should be overwritten, e.g., a logo or similar.

Consider the following, ocis is shipped with a default extension called image-viewer-dfx which contains a logo,
but the administrator wants to provide a custom logo for the image-viewer-dfx application.

This can be achieved by providing a custom logo in the WEB_APPS_PATH directory, e.g. WEB_APPS_PATH/image-viewer-dfx/logo.png.
Every other asset is loaded from the build in extension, but the logo is loaded from the custom directory.

The same applies for the manifest.json file, if the administrator wants to provide a custom manifest.json file.

Miscellaneous

Please note that ocis needs a restart to load new applications or changes to the apps.yaml file.

PR related information

Related Issue

• Fixes Easily Load Web Extensions #8392

How Has This Been Tested?

• local installation with a set of custom applications

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Technical debt
• Tests only (no source changes)

Checklist:

• Write Unit Tests
• Discuss with web-team if something is missing
• Critical review of JailJoin and FS, no breakout allowed
• Add Documentation (follow up pr once everything is done)
• Signature validation (followup pr)
• app loading cli (followup pr)

[fschade]

@butonic, @micbar, @kulmann, the current logic expects a file named web.apps.yml to be located within the BaseConfigPath/config directory.

in my opinion we should use something more agnostic like extensions.yml.

The reason why I'm torn is that when we mention web in the name, everyone assumes that these are only web apps (static files)...

But I think it would be great if we also allowed injecting proxy routes in the long term.

I know it's always difficult to look into the crystal ball, but I'm trying to prevent future migration efforts

what do you all mean?

[fschade]

we discussed the following adjustments:

• app configurations are done in the $OCIS_BASE_DATA_PATH/config/apps.yaml file
• custom apps are served from $OCIS_BASE_DATA_PATH/web/assets/apps or $WEB_APPS_PATH
• build in apps (compile time) are located in ocis_src_path/services/web/assets/apps
• the web static asset (ui) path is now /assets/core instead of /assets (build time and default fs location)
• WEB_ASSET_PATH is deprecated in favor of WEB_ASSET_CORE_PATH, a fallback mechanism and deprecation warning is build in.

cc.: @kulmann

[kobergj]

Found some typos...

[kulmann]

love it! ❤️

[fschade]

@dragonchaser can you please re-review and approve too, GH does not allow me to merge without your approval

[fschade]

I’m not happy with the fallbackfs, I need to apply one more change before we merge it.

[saw-jan]

we discussed the following adjustments:

• app configurations are done in the $OCIS_BASE_DATA_PATH/config/apps.yaml file
• custom apps are served from $OCIS_BASE_DATA_PATH/web/assets/apps or $WEB_APPS_PATH
• build in apps (compile time) are located in ocis_src_path/services/web/assets/apps
• the web static asset (ui) path is now /assets/core instead of /assets (build time and default fs location)
• WEB_ASSET_PATH is deprecated in favor of WEB_ASSET_CORE_PATH, a fallback mechanism and deprecation warning is build in.

cc.: @kulmann

was unable to load app with the latest changes and I was wondering why. Then found out that the env was changed
$WEB_APPS_PATH $WEB_ASSET_APPS_PATH

[mmattel]

@fschade IMPORTANT --> before merging, see my comment: #8523 (comment)

[sonarcloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
73.9% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud