Server Configuration¶
The server-conf.txt file: The conf folder inside the application folder contains a file named server-conf.txt. Open it with a text editor of your choice. In the file, there are various settings you may want to adjust. Each setting is documented in the file, and you may want to read the documentation for a particular setting before changing it. Moreover, after making any changes in the server-conf.txt file, you need to restart the server for the changes to take effect. For now, only the first four settings are of interest:
HttpPortHttpsPortSslCertChainSslPrivateKey
Ports and port numbers: Explaining what these four settings do requires going over some server-related concepts. To begin with, on every computer there are numbered communication channels called ports. Port numbers go from 0 to 65535, with port numbers 0–1024 reserved for well-known system services. The idea is that a server like DocFetcher Server can occupy one or more ports in order to listen and respond to any requests arriving at those ports. It is the clients who send the requests and receive the server’s responses, and for this they need to know the server computer’s network address, as well as the server’s port numbers. When you accessed the web interface on the previous page, the server computer’s address as seen “from within” was http://localhost, and the port number was 31190. Putting these two together gives us http://localhost:31190/, the full address needed to reach the server.
HTTP and HTTPS: Server-client communication via ports requires a communication protocol, and DocFetcher Server supports the two commonly used protocols HTTP and HTTPS. The difference between these two is that HTTP traffic is unencrypted, while HTTPS traffic is encrypted. This means HTTP is vulnerable to eavesdropping by third parties. HTTPS doesn’t have that problem, but comes with the hassle of having to obtain and maintain so-called SSL certificates. So usually you’d want to use either HTTP or HTTPS, and turn the other one off, depending on whether your particular environment calls for encrypted communication or not. For instance, if DocFetcher Server were to be deployed in a secured local company network, then HTTP would do just fine. On the other hand, it would be inadvisable to use HTTP instead of HTTPS for server-client communication over the internet.
HTTP port and HTTPS port: By default, DocFetcher Server has both HTTP and HTTPS enabled, and so by default it occupies two ports, one for HTTP and one for HTTPS. The respective port numbers are defined via the two settings HttpPort and HttpsPort in the server-conf.txt file. You can choose any port numbers between 1024 and 65535 for these two settings, as long as they don’t clash with one another, or with port numbers of other software running on the same computer. Setting HttpPort or HttpsPort to 0 will disable HTTP and HTTPS, respectively. Also, if you have a firewall installed, remember to configure the firewall to allow traffic on your chosen ports.
Port 80 and port 443: If you’re going to run DocFetcher Server as the “primary” server on the server computer, i.e., as a server that communicates directly with clients, rather than indirectly through another server, then you may want to set HttpPort = 80 or HttpsPort = 443, as 80 and 443 are the default ports for HTTP and HTTPS, respectively. This means that when a web address contains no port number, the latter is generally assumed to be 80 if the address starts with http://, and 443 if the address starts with https://. For instance, the address http://example.com is generally understood to be a shorthand for http://example.com:80, while the address https://example.com is generally understood to be a shorthand for https://example.com:443.
Subdirectory integration: An example of when you don’t want the server to handle clients directly is when you want to integrate the web interface of DocFetcher Server into a subdirectory of an existing website. For instance, the website could be https://example.com, and you want the web interface to be accessible at https://example.com/search. How to pull this off depends entirely on what web server the website runs on and so cannot be properly covered in this documentation. However, if that web server happens to be the commonly used Apache web server, then you can find some help on the page Apache Integration.
SSL certificate: Now, as stated above, if you’re going with HTTPS, you will need to obtain an SSL certificate. After that, you will need to tell DocFetcher Server via the two settings SslCertChain and SslPrivateKey where to find the certificate file and the accompanying private key file. For more info on what certificates and private keys DocFetcher Server expects, refer to the documentation in the server-conf.txt file. If you own a domain, such as example.com, you can get a free SSL certificate for that domain from Let’s Encrypt.
SSL certificate auto-renewal: As certificates usually have an expiration date, they must be renewed from time to time, either manually or automatically. When the certificate used by DocFetcher Server is renewed, remember to stop and restart the server so that it picks up the new certificate.
Recap: So, to recap, what are you supposed to do with the four settings listed above? Answer: If you’re going to disable either HTTP or HTTPS, then set HttpPort = 0 or HttpsPort = 0. If the server is supposed to communicate with the clients directly, then you’ll probably want HttpPort = 80 or HttpsPort = 443. Otherwise, you can just leave one of the two settings at its default value and set the other to 0, unless the default value clashes with the port number choice of other software on the same computer, in which case you can change the value to any available port number between 1024 and 65535. If you use HTTPS, then you need point DocFetcher Server to the SSL certificate files via the two settings SslCertChain and SslPrivateKey.
The AppName setting: Finally, there’s another setting in the server-conf.txt file that may be of interest to you: AppName. This one allows customizing the application title (by default “DocFetcher Server”) that is shown by the web interface in the browser window title and browser tab title. In addition, you are free to change the web interface’s favicon, by replacing the icon file img/favicon.ico with your own, perhaps to make the web interface more suitable for an enterprise environment.
