ownCloud Web with Custom Configuration

Introduction

The behavior of the embedded web frontend named ownCloud Web can be configured. This guide shows you how to do so.

Custom Compiled Web Assets

If you want to use your custom compiled web client assets instead of the embedded ones, then you can do that by setting the WEB_ASSET_PATH variable to point to your compiled files. See ownCloud Web / Getting Started and ownCloud Web / Setup with oCIS in the developer documentation for more details.

Using Custom Assets

Besides the configuration and application registration, in the process of loading the application assets, the system uses a mechanism to load custom assets.

This is very useful for cases where just a single asset should be overwritten, like a logo or similar.

Consider the following: Infinite Scale is shipped with a default web app named image-viewer-dfx which contains a logo, but the administrator wants to provide a custom logo for that application.

This can be achieved using the path defined via WEB_ASSET_APPS_PATH and adding a custom structure like WEB_ASSET_APPS_PATH/image-viewer-dfx/. Here you can add all custom assets to load like logo.png. On loading the web app, custom assets defined overwrite default ones.

This also applies for the manifest.json file, if the administrator wants to provide a custom one.

Extend Web UI With Apps

The Infinite Scale administrator is capable of providing custom web applications to the users. This feature is useful for organizations that want to provide third party or custom apps to their users. See the WebUI extensions repository for examples.

It’s important to note, that the feature is at the moment 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

  • Web applications are loaded, if added in the Infinite Scale source code, at build-time from <ocis_repo>/services/web/assets/apps. This cannot be manipulated at runtime.

  • Additionally, the administrator can provide custom applications by storing them in the path defined by the environment variable WEB_ASSET_APPS_PATH.

  • This environment variable defaults to the Infinite Scale base data directory $OCIS_BASE_DATA_PATH/web/assets/apps, but can be redefined with any path set manually.

  • The final list of available applications is composed of the built-in and the custom applications provided by the administrator via WEB_ASSET_APPS_PATH.

  • For example, if Infinite Scale would contain a built-in app named image-viewer-dfx and the administrator provides a custom application named image-viewer-obj via the WEB_ASSET_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:

    • Each application must be in its own directory accessed via WEB_ASSET_APPS_PATH.

    • Each application directory must contain a manifest.json file.

    Everything else is skipped and not considered as an application.

  • The manifest.json file contains the following fields:

    • entrypoint - required
      The entrypoint of the application like 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 apps.yaml.

Application Configuration

If a custom configuration is needed, the administrator must provide the required configuration inside the $OCIS_BASE_DATA_PATH/config/apps.yaml file.

An application manifest should never be changed manually, see Using Custom Assets for customisation.

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:

{
  "entrypoint": "index.js",
  "config": {
    "maxWidth": 1280,
    "maxHeight": 1280
  }
}

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": {
        "maxWidth": 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.

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

Miscellaneous

Please note that Infinite Scale, in particular the web service, needs a restart to load new applications or changes to the apps.yaml file.