webserver.js Configuration

The [webserverjs] Config Section

webserver.js is configured through the [webserverjs] section in the project configuration file. The available configuration options are largely the same as those of webclient_http.ctl and dashboard.ctl, but they must be placed in the [webserverjs] section instead of [wssServer] or [httpServer]. Dashboard-related settings that were previously in [httpServer] should also be moved to [webserverjs].

Port Configuration

The HTTPS port used by webserver.js is set via the httpsPort entry:

[webserverjs]
httpsPort = 8443

The default value is 8443. Change this value if another service already uses this port or if your deployment requires a different port assignment.

WSS (WebSocket Secure) connections are only supported via this encrypted port.

In addition to the encrypted port, webserver.js can listen for unencrypted HTTP connections on a separate port defined via the [webserverjs] httpPort entry:

[webserverjs]
httpsPort = 8443
httpPort = 8080

The default value is 0, which disables the entry. In this case webserver.js listens on the port defined via httpsPort only. If a port greater than 0 is defined, an additional plain HTTP listener is started that runs simultaneously with the HTTPS listener and serves the same routes. The port must be different from httpsPort.

Index Page

The indexPage entry defines which page is served as the default landing page. To serve the WinCC OA Dashboard, configure:

[webserverjs]
indexPage = "data/dashboard-wc/index.html"

Parallel Operation with webclient_http.ctl

When both webserver.js and the HTTP Server running webclient_http.ctl are active, two HTTP servers listen on different ports. In this configuration, the Dashboard can be opened from either port. However, this may lead to inconsistent results if the servers are configured differently or use different customizations. Always use the port configured for webserver.js when opening the Dashboard.

ULC UX Forwarding

webserver.js can forward ULC UX requests to the webclient_http.ctl handler. This is required for ULC UX functionality when using webserver.js as the backend.

To enable ULC UX forwarding, add the following entries to the [webserverjs] section:

[webserverjs]
ulcUxPort = 443
ulcUxHost = "localhost"
allowExternalResources = 1

The ulcUxPort and ulcUxHost specify the port and host of the HTTP Server instance running webclient_http.ctl.

The allowExternalResources entry must be set to 1 to allow embedding the ULC UX frame from a different host and/or port into the Dashboard.

On the HTTP Server side, CORS (Cross-Origin Resource Sharing) must be configured to allow requests from the webserver.js origin. Add the following entries to the [httpServer] section:

[httpServer]
accessControlAllowOrigin = "https://localhost:8443"
httpHeader = "Content-Security-Policy: frame-ancestors 'self' https://localhost:8443"
XFrameOptions = none

Adjust the server address and port number in these entries to match the httpsPort configured for webserver.js.

Windows Certificate Store

On Windows, webserver.js can load SSL certificates directly from the Windows Certificate Store instead of using file-based certificates. This avoids storing private key files on disk.

To enable this, set the cngHttpServerCert entry in the [general] section of the project configuration file:

[general]
securityMode = "cngCert"
cngCA = "USER:MY"
cngCert = "USER:MY:<THUMBPRINT>"
cngHttpServerCert = "USER:MY:<THUMBPRINT>"

webserver.js reads the certificate specified by cngHttpServerCert from the Windows Certificate Store at startup. If cngHttpServerCert is not set, the default file-based certificate.pem is used.

For the full description of the selector format and available store locations, see Windows Certificate Store Locations.

Dynamic Services Configuration

The behavior of dynamic service loading can be customized with the following config entries:

• [webserverjs] servicesEnabled
• [webserverjs] servicesWatchEnabled
• [webserverjs] servicesWatchDebounceMs
• [webserverjs] servicesDrainTimeoutMs