This guide is intended for system administrators and IT professionals of DocuWare on-premises installations. It covers the most important points for configuring and maintaining a frontend load balancer in a locally installed DocuWare system.
When to use a load balancer in DocuWare?
The DocuWare system is variably scalable and can be adapted to a wide variety of requirements. The five basic scaling types, their components and licenses are described in detail in the White Paper on-premises.
In general, a load balancer is used whenever several frontend servers are used. This is the case with the M-XL scaling forms of a DocuWare system.
A load balancer distributes the traffic from the clients to the servers accordingly.
Notes on installing DocuWare on multiple servers
To install a DocuWare system with multiple servers, run DocuWare Setup on each server machine.
Define a role for each server as described in the DocuWare Setup help. Consider the requirements of the selected scaling model.
Frontend role: Provides services for clients and users, includes Web Client, Platform Services and DocuWare Configuration.
Backend role: Provides services for background processing, e.g. workflows, processes and email capture.
Full text role: Provides services for full text processing.
A load balancer must be used whenever an installation with multiple front-end servers is used.
All Authentication Servers work in Local Mode. There is no further machine-to-machine communication. This means that the servers run independently of each other and can also be restarted separately.
Local mode is set by default. If you want, you can verify this in the configuration files of the Authentication Servers, the element is named AuthenticationServerSettings. The setting for the local mode is true:
<DWConfig>
<AuthenticationServerSettings LocalServersOnly="true" />
</DWConfig>
On all DocuWare servers with a frontend role, switch to the Application Initialization feature in the IIS Frontend Service System. Application Initialization helps to avoid long waiting times when loading applications.
When you set up DocuWare, you already specified the web page under which DocuWare will be installed in the IIS. In order for the Application Initialization to take effect, you need to adjust the IIS Application Pool on all frontend servers for this web site.
Use the following commands:
"%windir%\system32\inetsrv\appcmd.exe" set app /app.name:"Default Web Site/DocuWare/Platform" /serviceAutoStartEnabled:True /serviceAutoStartProvider:Service /preloadEnabled:True
"%windir%\system32\inetsrv\appcmd.exe" set config "Default Web Site/DocuWare/Platform" -section:system.webServer/applicationInitialization /doAppInitAfterRestart:"True" /skipManagedModules:"True"
"%windir%\system32\inetsrv\appcmd.exe" set config "Default Web Site/DocuWare/Platform" -section:system.webServer/applicationInitialization /+"[initializationPage='Home/Xsl',hostName='localhost']"
In case of a major update, e.g. as from DocuWare version 7.7 to 7.8, the application pool will be deleted. In this case, you will have to run the above commands again.
Check list for configuring a load balancer
DocuWare recommends for load balancing the variant Layer 7 with Web server and Application Request Routing (ARR).
ARR is a module of Microsoft's Internet Information Services (IIS) that is installed separately and connected in front of the DocuWare system. The ARR module acts as a reverse proxy or load balancer, distributing HTTP requests to the application servers behind it.
Load balancing in DocuWare is also possible with Layer 4. However, this variant is not covered by DocuWare Support.
To ensure that your load balancer works properly, keep the following points in mind when configuring your load balancer:
Session affinity
An existing client session must always be assigned to the same server. For this to happen, either the client's connections are always routed to the same server via the IP address, or the load balancer must be able to set cookies and extract and evaluate them for distributing the traffic.WebSocket transport protocol
The load balancer must support this protocol. The WebSocket transport protocol is a feature of the IIS role.Preserve host address
If the DocuWare system is preceded by a load balancer, the client does not communicate directly with DocuWare. The load balancer must be configured to pass the DocuWare address along with a request to DocuWare. This is usually done using a header that contains the original host address (DocuWare URL).Preserve client protocol
When SSL offloading is used in the load balancer, the load balancer communicates with the DocuWare server via HTTP. The load balancer must be configured to retain the client protocol (HTTPS). This is usually done using an X-Forwarded-Proto header that contains the original protocol used (HTTPS).Use consistent ports
If different endpoints are to communicate with each other in the network, such as the load balancer, firewall and DocuWare, you must ensure that all endpoints use the same ports. An exception is SSL offloading, where the port changes from 443 in the load balancer to 80 in the DocuWare frontend.
Here is an overview of the ports used in DocuWare:
Many load balancers also offer additional features such as SSL offloading or availability testing. It is up to the company's IT department to decide whether to use these features. They are not required for DocuWare:
SSL offloading
In this process, the client's SSL-based connection is terminated at the load balancer. The load balancer communicates with the frontend servers over HTTP, so decryption and encryption are offloaded from the frontend servers to the load balancer. SSL offloading can be configured and used on the load balancer.Health URL test
The load balancer periodically checks to see if the frontend servers are available and responding - for example, via a URL like http://<LoadbalancerFQDN>/DocuWare/Platform/Home.
In this way, the load balancer detects a failure in time and redirects the traffic to the "healthy" servers.Health live traffic test
This test monitors live traffic. However, this can have a negative impact on performance. We recommend to use the health live traffic test only in case of an acute problem and then only in combination with the health URL test.
However, it is up to your company's IT department to decide which tests to use for fail-safety.
Load balancing settings in DocuWare
For load balancing to work optimally, the following settings are required in DocuWare:
Customize machine keys of frontend web applications
All DocuWare servers with frontend role must use identical machine keys for the web applications DocuWare Forms, DocuWare Platform and Search/Search Service. To do this, adjust the machine keys in the web.config files of the applications
Otherwise, cookies created on one server cannot be used on another.Enter load balancer adress as web connection
For security reasons, DocuWare only accepts addresses that are entered as web connections. Therefore, enter the address of the load balancer in DocuWare Administration > DocuWare Web Connection > HTTP Root.Check local computer name
To ensure smooth communication between DocuWare services, check that the local computer name is specified in the dwmachine.config file on all frontend servers.
The text file dwmachine.config can be found in the following path: %AllUsersProfile%\DocuWare\ServerConfig. The computer name is specified in the LocalWebServices line.
However, if multiple servers are used for load balancing, then the public address of the load balancer cluster must be entered at this point in dwmachine.config. In this case, make sure that all frontend servers within the network can reach this address.
General notes:
Encrypt with SSL/TLS
For security reasons encrypt the entire HTTP traffic of your DocuWare on-premises with SSL/TLS. This is mandatory for DocuWare Version 7.6 and later.
Here is an example how you can install an SSL certificate.Configure Azure Message Bus
If you are using Azure as hoster, read here the instructions on how to configure DocuWare for the Azure Service Bus.
Maintenance of a DocuWare system with load balancing
A DocuWare system with load balancer is to be maintained like any other productive DocuWare system. In addition, the following aspects are particularly important:
Adjust settings again after a DocuWare update: After a major DocuWare update, such as from version 7.8 to 7.9, you will need to adjust your DocuWare installation in two places:
For your front-end servers, renew the settings for your application pool in IIS.
The update overwrites the web.config file. Therefore set the machine keys again on all updated servers. All servers with frontend roles must use identical keys.
Note that you should use the same keys as before upgrading so that sessions started before upgrading can remain active. The previous keys are kept in the Server Setup Backup folder after an update: %AllUsersProfile%\DocuWare\ConfigBackup\.
Databases and backup: The stability of DocuWare depends, among other things, on the integrity and availability of the databases. Therefore, make sure that you back up your databases regularly. There is no DocuWare mechanism that automatically backs up the databases and storage locations. Backing up DocuWare databases and storage locations is the responsibility of corporate IT. For more on backing up databases, the documents and storage locations, and full-text data, see the White Paper On-Premises - Backup.
You should also use database indexes for the servers of your DocuWare databases to increase the speed of queries, especially in complex DocuWare installations.