Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 22 commits into from
Mar 5, 2024

Conversation

fschade
Copy link
Contributor

@fschade fschade commented Feb 25, 2024

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

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 fschade self-assigned this Feb 25, 2024
@fschade fschade changed the title enhancement: allow ocis to provide custom web applications [full-ci] enhancement: allow ocis to provide custom web applications Feb 25, 2024
@fschade
Copy link
Contributor Author

fschade commented Feb 26, 2024

@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 fschade force-pushed the web-apps branch 3 times, most recently from 118d0b2 to dbdef9a Compare February 26, 2024 16:58
@fschade fschade marked this pull request as ready for review February 28, 2024 12:06
ocis-pkg/log/log_test.go Outdated Show resolved Hide resolved
ocis-pkg/x/io/fsx/sub.go Outdated Show resolved Hide resolved
services/search/pkg/engine/bleve.go Show resolved Hide resolved
ocis-pkg/x/io/fsx/sub_test.go Outdated Show resolved Hide resolved
ocis-pkg/log/log.go Outdated Show resolved Hide resolved
@fschade
Copy link
Contributor Author

fschade commented Feb 29, 2024

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

services/web/README.md Outdated Show resolved Hide resolved
services/web/README.md Outdated Show resolved Hide resolved
services/web/README.md Outdated Show resolved Hide resolved
Copy link
Collaborator

@kobergj kobergj left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Found some typos...

services/web/README.md Outdated Show resolved Hide resolved
services/web/README.md Outdated Show resolved Hide resolved
services/web/README.md Outdated Show resolved Hide resolved
Copy link
Member

@kulmann kulmann left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

love it! ❤️

@fschade
Copy link
Contributor Author

fschade commented Feb 29, 2024

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

@fschade fschade marked this pull request as draft February 29, 2024 22:47
@fschade
Copy link
Contributor Author

fschade commented Feb 29, 2024

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

@saw-jan
Copy link
Member

saw-jan commented Mar 1, 2024

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

services/web/README.md Outdated Show resolved Hide resolved
services/web/README.md Outdated Show resolved Hide resolved
@mmattel
Copy link
Contributor

mmattel commented Mar 5, 2024

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

Copy link

sonarcloud bot commented Mar 5, 2024

@fschade fschade merged commit 6814c61 into owncloud:master Mar 5, 2024
4 checks passed
ownclouders pushed a commit that referenced this pull request Mar 5, 2024
…8523)

* enhancement: allow ocis to provide custom web applications

* enhancement: add an option to disable web apps

* test: add default logger tests

* test: add app loading tests

* test: add asset server tests

* enhancement: make use of dedicated app conf file and app asset paths

* enhancement: adjust asset locations and deprecate WEB_ASSET_PATH

* enhancement: get rid of default logger and use the service level logger instead

* Apply suggestions from code review

Co-authored-by: Benedikt Kulmann <benedikt@kulmann.biz>
Co-authored-by: kobergj <juliankoberg@googlemail.com>

* enhancement: use basename as app id

* Apply suggestions from code review

Co-authored-by: Martin <github@diemattels.at>

* enhancement: use afero as fs abstraction

* enhancement: simplify logo upload

* enhancement: make use of introductionVersion field annotations

---------

Co-authored-by: Benedikt Kulmann <benedikt@kulmann.biz>
Co-authored-by: kobergj <juliankoberg@googlemail.com>
Co-authored-by: Martin <github@diemattels.at>
@micbar micbar mentioned this pull request Jun 19, 2024
24 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
Archived in project
Development

Successfully merging this pull request may close these issues.

Easily Load Web Extensions
7 participants