Web

Abstract

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
Web UI Configuration
Web Apps
Miscellaneous
Example Yaml Config

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

Single configuration settings of the embedded web UI can be defined via WEB_OPTION_xxx environment variables.
A json based configuration file can be used via the WEB_UI_CONFIG_FILE environment variable.
If a json based configuration file is used, 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 Themes

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

Additionally, the administrator can provide custom themes by storing it in the path defined by the environment variable WEB_ASSET_THEMES_PATH.

With the theme root directory defined, the system needs to know which theme to use. This can be done by setting the WEB_UI_THEME_PATH environment variable.

The final theme is composed of the built-in and the custom theme provided by the administrator via WEB_ASSET_THEMES_PATH and WEB_UI_THEME_PATH.

For example, Infinite Scale by default contains a built-in ownCloud theme. If the administrator provides a custom theme via the WEB_ASSET_THEMES_PATH directory like, WEB_ASSET_THEMES_PATH/owncloud/themes.json, this one will be used instead of the built-in one.

Some theme keys are mandatory, like the common.shareRoles settings. Such mandatory keys are injected automatically at runtime if not provided.

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 contains a built-in extension 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 WebUI.

Application Structure

Applications always have to follow a strict structure.
Everything else is skipped and not considered as an application.
- Each application must be in its own directory accessed via WEB_ASSET_APPS_PATH.
- Each application directory must contain a manifest.json file.
- Each application directory can contain a config.json file.
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.

NOTE: 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

optional each application can have its own configuration file, which will be loaded by the WEB service.

{
  "config": {
    "maxWidth": 320
  }
}

The Merge order is as follows: local.config overwrites > global.config overwrites > manifest.config. The result will be:

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

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

disabled - optional
Defaults to false. If set to true, the application will not be loaded.

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 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.

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.

Example Yaml Config

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131


# Autogenerated
# Filename: web-config-example.yaml

tracing:
  enabled: false
  type: ""
  endpoint: ""
  collector: ""
log:
  level: ""
  pretty: false
  color: false
  file: ""
debug:
  addr: 127.0.0.1:9104
  token: ""
  pprof: false
  zpages: false
http:
  addr: 127.0.0.1:9100
  tls:
    enabled: false
    cert: ""
    key: ""
  root: /
  cache_ttl: 604800
  cors:
    allow_origins:
    - https://localhost:9200
    allow_methods:
    - OPTIONS
    - HEAD
    - GET
    - PUT
    - PATCH
    - POST
    - DELETE
    - MKCOL
    - PROPFIND
    - PROPPATCH
    - MOVE
    - COPY
    - REPORT
    - SEARCH
    allow_headers:
    - Origin
    - Accept
    - Content-Type
    - Depth
    - Authorization
    - Ocs-Apirequest
    - If-None-Match
    - If-Match
    - Destination
    - Overwrite
    - X-Request-Id
    - X-Requested-With
    - Tus-Resumable
    - Tus-Checksum-Algorithm
    - Upload-Concat
    - Upload-Length
    - Upload-Metadata
    - Upload-Defer-Length
    - Upload-Expires
    - Upload-Checksum
    - Upload-Offset
    - X-HTTP-Method-Override
    allow_credentials: false
asset:
  core_path: /var/lib/ocis/web/assets/core
  themes_path: /var/lib/ocis/web/assets/themes
  apps_path: /var/lib/ocis/web/assets/apps
file: ""
web:
  theme_server: https://localhost:9200
  theme_path: /themes/owncloud/theme.json
  config:
    server: https://localhost:9200
    oidc:
      metadata_url: https://localhost:9200/.well-known/openid-configuration
      authority: https://localhost:9200
      client_id: web
      response_type: code
      scope: openid profile email
      post_logout_redirect_uri: ""
    apps:
    - files
    - search
    - text-editor
    - pdf-viewer
    - external
    - admin-settings
    - epub-reader
    - preview
    - app-store
    applications: []
    external_apps: []
    options:
      openAppsInTab: false
      accountEditLink: null
      disableFeedbackLink: false
      feedbackLink: null
      runningOnEos: false
      cernFeatures: false
      upload: null
      editor: null
      contextHelpersReadMore: true
      logoutUrl: ""
      loginUrl: ""
      tokenStorageLocal: true
      disabledExtensions: []
      embed:
        enabled: ""
        target: ""
        messagesOrigin: ""
        delegateAuthentication: false
        delegateAuthenticationOrigin: ""
      userListRequiresFilter: false
      concurrentRequests:
        resourceBatchActions: 0
        sse: 0
        shares:
          create: 0
          list: 0
    styles: []
    scripts: []
    custom_translations: []
apps: {}
token_manager:
  jwt_secret: ""
gateway_addr: com.owncloud.api.gateway

Environment Variables

Name	Type	Default Value	Description
OCIS_TRACING_ENABLED WEB_TRACING_ENABLED	bool	false	Activates tracing.
OCIS_TRACING_TYPE WEB_TRACING_TYPE	string		The type of tracing. Defaults to ‘’, which is the same as ‘jaeger’. Allowed tracing types are ‘jaeger’ and ’’ as of now.
OCIS_TRACING_ENDPOINT WEB_TRACING_ENDPOINT	string		The endpoint of the tracing agent.
OCIS_TRACING_COLLECTOR WEB_TRACING_COLLECTOR	string		The HTTP endpoint for sending spans directly to a collector, i.e. http://jaeger-collector:14268/api/traces. Only used if the tracing endpoint is unset.
OCIS_LOG_LEVEL WEB_LOG_LEVEL	string		The log level. Valid values are: ‘panic’, ‘fatal’, ’error’, ‘warn’, ‘info’, ‘debug’, ’trace’.
OCIS_LOG_PRETTY WEB_LOG_PRETTY	bool	false	Activates pretty log output.
OCIS_LOG_COLOR WEB_LOG_COLOR	bool	false	Activates colorized log output.
OCIS_LOG_FILE WEB_LOG_FILE	string		The path to the log file. Activates logging to this file if set.
WEB_DEBUG_ADDR	string	127.0.0.1:9104	Bind address of the debug server, where metrics, health, config and debug endpoints will be exposed.
WEB_DEBUG_TOKEN	string		Token to secure the metrics endpoint.
WEB_DEBUG_PPROF	bool	false	Enables pprof, which can be used for profiling.
WEB_DEBUG_ZPAGES	bool	false	Enables zpages, which can be used for collecting and viewing in-memory traces.
WEB_HTTP_ADDR	string	127.0.0.1:9100	The bind address of the HTTP service.
OCIS_HTTP_TLS_ENABLED	bool	false	Activates TLS for the http based services using the server certifcate and key configured via OCIS_HTTP_TLS_CERTIFICATE and OCIS_HTTP_TLS_KEY. If OCIS_HTTP_TLS_CERTIFICATE is not set a temporary server certificate is generated - to be used with PROXY_INSECURE_BACKEND=true.
OCIS_HTTP_TLS_CERTIFICATE	string		Path/File name of the TLS server certificate (in PEM format) for the http services.
OCIS_HTTP_TLS_KEY	string		Path/File name for the TLS certificate key (in PEM format) for the server certificate to use for the http services.
WEB_HTTP_ROOT	string	/	Subdirectory that serves as the root for this HTTP service.
WEB_CACHE_TTL	int	604800	Cache policy in seconds for ownCloud Web assets.
OCIS_CORS_ALLOW_ORIGINS WEB_CORS_ALLOW_ORIGINS	[]string	[https://localhost:9200]	A list of allowed CORS origins. See following chapter for more details: Access-Control-Allow-Origin at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin. See the Environment Variable Types description for more details.
OCIS_CORS_ALLOW_METHODS WEB_CORS_ALLOW_METHODS	[]string	[OPTIONS HEAD GET PUT PATCH POST DELETE MKCOL PROPFIND PROPPATCH MOVE COPY REPORT SEARCH]	A list of allowed CORS methods. See following chapter for more details: Access-Control-Request-Method at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Method. See the Environment Variable Types description for more details.
OCIS_CORS_ALLOW_HEADERS WEB_CORS_ALLOW_HEADERS	[]string	[Origin Accept Content-Type Depth Authorization Ocs-Apirequest If-None-Match If-Match Destination Overwrite X-Request-Id X-Requested-With Tus-Resumable Tus-Checksum-Algorithm Upload-Concat Upload-Length Upload-Metadata Upload-Defer-Length Upload-Expires Upload-Checksum Upload-Offset X-HTTP-Method-Override]	A list of allowed CORS headers. See following chapter for more details: Access-Control-Request-Headers at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Request-Headers. See the Environment Variable Types description for more details.
OCIS_CORS_ALLOW_CREDENTIALS WEB_CORS_ALLOW_CREDENTIALS	bool	false	Allow credentials for CORS. See following chapter for more details: Access-Control-Allow-Credentials at https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials.
WEB_ASSET_CORE_PATH	string	/var/lib/ocis/web/assets/core	Serve ownCloud Web assets from a path on the filesystem instead of the builtin assets. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH/web/assets/core
OCIS_ASSET_THEMES_PATH WEB_ASSET_THEMES_PATH	string	/var/lib/ocis/web/assets/themes	Serve ownCloud themes from a path on the filesystem instead of the builtin assets. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH/web/assets/themes
WEB_ASSET_APPS_PATH	string	/var/lib/ocis/web/assets/apps	Serve ownCloud Web apps assets from a path on the filesystem instead of the builtin assets. If not defined, the root directory derives from $OCIS_BASE_DATA_PATH/web/assets/apps
WEB_UI_CONFIG_FILE	string		Read the ownCloud Web json based configuration from this path/file. The config file takes precedence over WEB_OPTION_xxx environment variables. See the text description for more details.
OCIS_URL WEB_UI_THEME_SERVER	string	https://localhost:9200	Base URL to load themes from. Will be prepended to the theme path.
WEB_UI_THEME_PATH	string	/themes/owncloud/theme.json	Path to the theme json file. Will be appended to the URL of the theme server.
OCIS_URL WEB_UI_CONFIG_SERVER	string	https://localhost:9200	URL, where the oCIS APIs are reachable for ownCloud Web.
WEB_OIDC_METADATA_URL	string	https://localhost:9200/.well-known/openid-configuration	URL for the OIDC well-known configuration endpoint. Defaults to the oCIS API URL + ‘/.well-known/openid-configuration’.
OCIS_URL OCIS_OIDC_ISSUER WEB_OIDC_AUTHORITY	string	https://localhost:9200	URL of the OIDC issuer. It defaults to URL of the builtin IDP.
OCIS_OIDC_CLIENT_ID WEB_OIDC_CLIENT_ID	string	web	The OIDC client ID which ownCloud Web uses. This client needs to be set up in your IDP. Note that this setting has no effect when using the builtin IDP.
WEB_OIDC_RESPONSE_TYPE	string	code	The OIDC response type to use for authentication.
WEB_OIDC_SCOPE	string	openid profile email	OIDC scopes to request during authentication to authorize access to user details. Defaults to ‘openid profile email’. Values are separated by blank. More example values but not limited to are ‘address’ or ‘phone’ etc.
WEB_OIDC_POST_LOGOUT_REDIRECT_URI	string		This value needs to point to a valid and reachable web page. The web client will trigger a redirect to that page directly after the logout action. The default value is empty and redirects to the login page.
WEB_OPTION_OPEN_APPS_IN_TAB	bool	false	Configures whether apps and extensions should generally open in a new tab. Defaults to false.
WEB_OPTION_DISABLE_FEEDBACK_LINK	bool	false	Set this option to ’true’ to disable the feedback link in the top bar. Keeping it enabled by setting the value to ‘false’ or with the absence of the option, allows ownCloud to get feedback from your user base through a dedicated survey website.
WEB_OPTION_RUNNING_ON_EOS	bool	false	Set this option to ’true’ if running on an EOS storage backend (https://eos-web.web.cern.ch/eos-web/) to enable its specific features. Defaults to ‘false’.
WEB_OPTION_CONTEXTHELPERS_READ_MORE	bool	true	Specifies whether the ‘Read more’ link should be displayed or not.
WEB_OPTION_LOGOUT_URL	string		Adds a link to the user’s profile page to point him to an external page, where he can manage his session and devices. This is helpful when an external IdP is used. This option is disabled by default.
WEB_OPTION_LOGIN_URL	string		Specifies the target URL to the login page. This is helpful when an external IdP is used. This option is disabled by default. Example URL like: https://www.myidp.com/login.
WEB_OPTION_TOKEN_STORAGE_LOCAL	bool	true	Specifies whether the access token will be stored in the local storage when set to ’true’ or in the session storage when set to ‘false’. If stored in the local storage, login state will be persisted across multiple browser tabs, means no additional logins are required.
WEB_OPTION_DISABLED_EXTENSIONS	[]string	[]	A list to disable specific Web extensions identified by their ID. The ID can e.g. be taken from the ‘index.ts’ file of the web extension. Example: ‘com.github.owncloud.web.files.search,com.github.owncloud.web.files.print’. See the Environment Variable Types description for more details.
WEB_OPTION_EMBED_ENABLED	string		Defines whether Web should be running in ’embed’ mode. Setting this to ’true’ will enable a stripped down version of Web with reduced functionality used to integrate Web into other applications like via iFrame. Setting it to ‘false’ or not setting it (default) will run Web as usual with all functionality enabled. See the text description for more details.
WEB_OPTION_EMBED_TARGET	string		Defines how Web is being integrated when running in ’embed’ mode. Currently, the only supported options are ’’ (empty) and ’location’. With ’’ which is the default, Web will run regular as defined via the ’embed.enabled’ config option. With ’location’, Web will run embedded as location picker. Resource selection will be disabled and the selected resources array always includes the current folder as the only item. See the text description for more details.
WEB_OPTION_EMBED_MESSAGES_ORIGIN	string		Defines a URL under which Web can be integrated via iFrame in ’embed’ mode. Note that setting this is mandatory when running Web in ’embed’ mode. Use ‘*’ as value to allow running the iFrame under any URL, although this is not recommended for security reasons. See the text description for more details.
WEB_OPTION_EMBED_DELEGATE_AUTHENTICATION	bool	false	Defines whether Web should require authentication to be done by the parent application when running in ’embed’ mode. If set to ’true’ Web will not try to authenticate the user on its own but will require an access token coming from the parent application. Defaults to being unset.
WEB_OPTION_EMBED_DELEGATE_AUTHENTICATION_ORIGIN	string		Defines the host to validate the message event origin against when running Web in ’embed’ mode with delegated authentication. Defaults to event message origin validation being omitted, which is only recommended for development setups.
WEB_OPTION_USER_LIST_REQUIRES_FILTER	bool	false	Defines whether one or more filters must be set in order to list users in the Web admin settings. Set this option to ’true’ if running in an environment with a lot of users and listing all users could slow down performance. Defaults to ‘false’.
WEB_OPTION_CONCURRENT_REQUESTS_RESOURCE_BATCH_ACTIONS	int	0	Defines the maximum number of concurrent requests per file/folder/space batch action. Defaults to 4.
WEB_OPTION_CONCURRENT_REQUESTS_SSE	int	0	Defines the maximum number of concurrent requests in SSE event handlers. Defaults to 4.
WEB_OPTION_CONCURRENT_REQUESTS_SHARES_CREATE	int	0	Defines the maximum number of concurrent requests per sharing invite batch. Defaults to 4.
WEB_OPTION_CONCURRENT_REQUESTS_SHARES_LIST	int	0	Defines the maximum number of concurrent requests when loading individual share information inside listings. Defaults to 2.
OCIS_JWT_SECRET WEB_JWT_SECRET	string		The secret to mint and validate jwt tokens.
WEB_GATEWAY_GRPC_ADDR	string	com.owncloud.api.gateway	The bind address of the GRPC service.

Web