opencloud/services/web

Web

The web service embeds and serves the static files for the Infinite Scale Web Client. Note that clients will respond with a connection error if the web service is not available.

The web service also provides a minimal API for branding functionality like changing the logo shown.

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 for more details.

Web UI Configuration

Note that single configuration settings of the embedded web UI can be defined via WEB_OPTION_xxx environment variables.

If a json based configuration file is used via the WEB_UI_CONFIG_FILE environment variable, these configurations take precedence over single options set.

Web UI Options

Besides theming, the behavior of the web UI can be configured via options. See the environment variables WEB_OPTION_xxx for more details.

Web UI Config File

When defined via the WEB_UI_CONFIG_FILE environment variable, the configuration of the web UI can be made with a json based file.

Embedding Web

Web can be consumed by another application in a stripped down version called “Embed mode”. This mode is supposed to be used in the context of selecting or sharing resources.

For more details see the developer documentation ownCloud Web / Embed Mode. See the environment variables: WEB_OPTION_MODE and WEB_OPTION_EMBED_TARGET to configure the embedded mode.

Web Apps

The administrator of the environment 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.

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

Web applications are loaded from the buildin FS in the ocis binary, e.g. ocis_src_path/services/web/assets/apps this cannot be manipulated at runtime only at build-time.

Additionally, the administrator can provide custom applications in one of the following ways:

• By loading a web application from the default ocis base directory, e.g. $OCIS_BASE_DATA_PATH/web/assets/apps (default behavior).
• By loading a web application from a user-provided path, by setting the WEB_ASSET_APPS_PATH environment variable.

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

For example, if ocis would contain a build in extension named image-viewer-dfx and the administrator provides a custom application named image-viewer-obj in 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 as follows:

• each application must be in its own directory
• 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, 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:

{
  "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 know; 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 named 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_ASSET_APPS_PATH directory, e.g. WEB_ASSET_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.