Installation overview

Introduction

The following chapters describe the procedure for installing and setting up Infrarch Cloud Office. This procedure is not particularly complicated but has some steps that require attention. As you will note, most of the content is actually related to setting up the webserver needed to run Infrarch Cloud Office.

Requirements

Infrarch Cloud Office has been written in Java Server Pages. It has been developed to run with Apache Tomcat webserver and Oracle Java.

The system has been developed and tested primarily on Windows. In principle there is nothing to prevent it from running on other operating systems. Some parts of the installation procedure described are applicable specifically for Windows.

This installation guide assumes that you have purchased Infrarch Cloud Office and have downloaded the installation package from the link provided.

Summary of the installation procedure

The following steps must be performed in order to install the system:

  • install Java
  • install and configure Apache Tomcat
  • set up security certificates for SSL/TLS
  • configure your firewall, network, etc.
  • install and configure Infrarch Cloud Office

Some of the needed components may already be in place on the machine you wish to install the system to. It is still recommended to follow (or at least review) the installation procedure in order to properly set up all components.

Installing Java

Download Java

Java may be downloaded from the following address:

https://java.com/en/download/manual.jsp

Even if you already have Java on your machine, it is recommended to update it to the latest version.

You may choose to download the 32-bit or the 64-bit version for your operating system. If you are running a 64-bit operating system, there should be nothing preventing you from opting for the 64-bit version of Java.

Install Java

Installing Java is straightforward and leaving the default directories works just fine. Once you have installed or updated Java you may proceed with the next step.

Installing Apache Tomcat

Download Apache Tomcat

Apache Tomcat may be downloaded from the following address:

https://tomcat.apache.org/

Even if you already have Apache Tomcat on your machine, it is recommended to update it to the latest stable version. If you are unsure which exactly the latest stable version is, you may refer to this page:

https://tomcat.apache.org/whichversion.html

When selecting the version to download, make sure that it is compatible with the Java version you have previously installed. The required Java version is noted in the beginning of README and release note files.

When selecting the package to download you must make sure that the binary distribution has been compiled for the same processor architecture as your Java runtime environment. You can run 32-bit Apache Tomcat on 32-bit Java and 64-bit Apache Tomcat on 64-bit Java but 64-bit Apache Tomcat on 32-bit Java will not work. If you select the 32-bit/64-bit Windows Service Installer it will automatically determine the appropriate Tomcat version to install.

Install Apache Tomcat

The following notes assume installation with the Windows Service Installer. If a ZIP package is selected or another operating systems is being used, generally the same elements will have to be configured manually.

The installer will first ask for the components to install. You may leave 'Examples', 'Host Manager' and 'Documentation' unchecked, as they will not be necessary, but may leave the 'Manager' application, which makes deploying and upgrading Infrarch Cloud Office more convenient. Also make sure that the 'Service Startup' option is checked - this way the Tomcat service will automatically start when the server starts.

The next dialog specifies port numbers and administrator name and password. If Apache Tomcat will not be behind another server, it is recommended to change the HTTP port to 80. (In this case later you should also change the HTTPS port from 8443 to 443; details in the following chapters.) You must define an administaror user name and password to access the Manager web application. By default only users logged in from the server may gain access to the Manager. Nevertheless the administaror password must be strong.

Next the Java Runtime Environment directory must be specified. The installer is capable of finding the correct directory, you must only verify and confirm it.

Finally, the Apache Tomcat home directory must be set. There is no problem with leaving the default.

Configuring Apache Tomcat

Configure Apache Tomcat

The following notes assume a Windows installation.

Start Tomcat Monitor and open the configuration dialog. In the 'General' settings section you must verify that the startup type is set to 'Automatic' instead of 'Manual'. Next, in the 'Java' section you must set the following parameters:

-Dfile.encoding=UTF-8

-Duser.country=XX

-Duser.language=yy

'XX' represents your country ISO 3166 alpha-2 (that is, two letter) code and 'yy' is your country ISO 639 alpha-2 language code.

Finally, set the initial memory pool to 384 MB and the maximum memory pool to 1024 MB. These values work fine under most conditions.

Tune the Connectors

At this point you may configure the Connectors to work with UTF-8 encoding and finish setting port numbers. You may edit the file $CATALINA_BASE/conf/server.xml so that the HTTP Connector looks something like:

<Connector port="80" protocol="HTTP/1.1"

connectionTimeout="20000" URIEncoding="UTF-8" redirectPort="443" />

Note: $CATALINA_BASE is the root directory of the instance of Tomcat being configured. In case of a single webserver instance, $CATALINA_BASE will be the same as $CATALINA_HOME - and that is the directory Tomcat was installed in.

Then you may uncomment the HTTPS Connector for port 8443 and make it look something like:

<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true"

URIEncoding="UTF-8" maxThreads="150" scheme="https" secure="true"

clientAuth="false" sslProtocol="TLS" />

You must also amend the redirectPort attributes of all other Connectors from 8443 to 443.

Setting up SSL/TLS (part 1)

Introduction

SSL (Secure Sockets Layer) and its successor TLS (Transport Layer Security) ensure that the connection between the client and server is secure by encrypting it. The other important feature of SSL/TLS is that when establishing a connection the server presents its credentials to the client in assurance that it is indeed who it claims to be. Setting up a secure connection is essential, if you are to allow connections to your system from the outside world.

Create keystore and private key

To create keystore and private key go to the command line and then switch to the %JAVA_HOME%\bin directory (%JAVA_HOME% being the directory your Java Runtime Environment is installed in). This will take you to the directory which contains the keytool command. Then type:

keytool -genkey -alias tomcat -keyalg RSA

You will be prompted to enter a keystore password. You will need this password to access the keystore and it will later have to be provided to Tomcat, so that it can also access the keystore.

Next you will be prompted to enter a number of attributes of the certificate:

  • First and last name (Common Name, CN): enter the domain of your website (i.e. 'xyz.com') in this field. Note that this field must match exactly your domain name. For example, if you have specified 'xyz.com', trying to use the certificate on 'www.xyz.com' will result in a security warning to the clients attempting to connect.
  • Organizational Unit (OU): the name of the unit making the request. Note that if the name includes symbols like &, @, #, or similar, they must be omitted.
  • Organization (O): the name of your organization. Note that if the name includes symbols like &, @, #, or similar, they must be omitted.
  • Locality or City (L): the city or town name of the organization must be entered.
  • State or Province (S): the name must be spelled out completely and not abbreviated.
  • Country Name (C): the two-letter code of the country must be entered, for example 'US', 'CA', etc.

Next you must enter a password for the private key alias. Press 'Enter' to set the private key password to the same password used for the keystore.

Note: You must keep the private key and the keystore password. If lost they cannot be retrieved.

Once completed, this command will create a new Java Keystore file named .keystore. It will be located in the home directory of the user under which you run the command. For now you may leave it there, so that you do not have to tell keytool where the keystore is and how it is named each time you run the command.

Setting up SSL/TLS (part 2)

Generate and submit a certificate signing request (CSR)

At the command line type:

keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr

This will generate a file named certreq.csr in the directory of keytool.

Note: At this point you may create a backup copy of the keystore file, which will help, if there are later problems with importing the signed certificate into the keystore.

You may now open the generated file with a plain text editor like Notepad or Notepad++. The contents will look something like:

-----BEGIN CERTIFICATE-----

MIIDjzCCAnegAwIBAgIEG/AiUDANBgkqhkiG9w00iw...

-----END CERTIFICATE-----

You must copy and paste all of this text to the form provided by the Certificate Authority on their webpage and follow their instructions.

Download the signed certificate

When available, download the certificate from the Certificate Authority. If it already is in PKCS #7 format (the file has extension .p7s meaning electronic signature in PKCS #7 format), you may skip this step. Otherwise you will need to convert it to PKCS #7.

To convert the certificate in Windows, open the certificate file (double-click on it) and go to the 'Details' section. Press 'Copy to File', select PKCS #7 as export format and finish the operation.

Import Certificate Authority's certificate

At the command line type:

keytool -import -alias root -trustcacerts -file ca_cert.crt

If the import is successful, the Certificate Authority's certificate will now be in your keystore.

Import the signed certificate

At the command line type:

keytool -import -alias tomcat -file cert.p7s

If the import is successful, the signed certificate will now be in your keystore. To verify that all is in order you may list the contents of the keystore by typing:

keytool -list

The result should look something like this:

Enter keystore password:

Keystore type: JKS

Keystore provider: SUN

Your keystore contains 2 entries

root, 10.07.2016, trustedCertEntry,

Certificate fingerprint (SHA1): C9:6E:DB:C7:1A:B0:50:79:F6:1A:CD:F3:D8:DC:5D:B6:1E:B7:5F:B6

tomcat, 10.07.2016, PrivateKeyEntry,

Certificate fingerprint (SHA1): 73:A7:B5:2E:41:C2:AA:DF:44:F3:0E:53:0B:D3:85:79:00:8C:27:42

Setting up SSL/TLS (part 3)

Configure the HTTPS Connector

After you have succesfully imported the signed certificate into your keystore you may copy the file .keystore from the directory of the active user to directory $CATALINA_BASE/conf/ and edit the file $CATALINA_BASE/conf/server.xml to look something like:

<Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true"

URIEncoding="UTF-8" maxThreads="150" scheme="https" secure="true"

clientAuth="false" sslProtocol="TLS"

keystoreFile="conf/.keystore" keystorePass="password" keyAlias="tomcat" />

Tomcat should now be able to serve HTTPS requests on port 443. Note that if you have only one private key in the keystore (that is, if you follow the default procedure), you may omit the keyAlias attribute.

Enforce HTTPS

Even though you have enabled HTTPS users will still be able to establish insecure connections using HTTP. To address this, you may place the following code in $CATALINA_BASE/conf/web.xml file:

<security-constraint>

  <web-resource-collection>

    <web-resource-name>ROOT</web-resource-name>

    <url-pattern>/*</url-pattern>

  </web-resource-collection>

  <user-data-constraint>

    <transport-guarantee>CONFIDENTIAL</transport-guarantee>

  </user-data-constraint>

</security-constraint>

This way clients will always use HTTPS regardless to the type of connection attempt.

Other settings

Firewall

It may be obvious, but do not forget to add rules to your firewall for the ports the webserver will be using. The procedure for adding these rules will vary depending on your firewall but should not be complicated.

Port forwarding

As IP addresses in the local network change from time to time, you must first make the IP address of your server static. After you have done that, go to the address of your router (it will be something like http://192.168.0.1) and log in as administrator. For the exact IP address of your router and administrator's account name and password you must consult router's documentation.

Having logged in, go to the port forwarding section. In the list of rules enter a rule for each of the ports you intend to use - 80 for HTTP and 443 for HTTPS. These rules typically comprise of the local IP address of your server, the incoming port and the server port that must be used (in this case the same as the incoming port).

Domain Name Server

If you have a domain registered and wish to use it for accessing the system, then you should configure the DNS you will be using to point to the public IP address of your network. The procedure for this depends on your Internet service provider.

Server Host Name

When you are using the system from your local network you would do so by typing server's private IP address. This, however, is not very convenient for daily use. Alternatively you may set a host name for the server on clients' machines. To do this open the file \Windows\System32\drivers\etc\hosts and add a new line containing server's IP address and the host name you wish to access it by, for example:

192.168.0.33 cloud_office

The change will take effect immediately and you will be able to access the system on http://cloud_office. Note, however, that file share links generated on a computer where a host name for the server is set may not be accessible on other people's computers.

Installing Infrarch Cloud Office

Deploying the web application

Infrarch Cloud Office is distributed as a single WAR (web application archive) file named ROOT.war. Once you have downloaded it and have successfully installed Apache Tomcat, you may install the system using Tomcat's built in Manager application. For that, do the following:

  • Go to http://localhost/manager. You will be prompted to enter administrator's user name and password you have selected during Tomcat's installation.
  • Go to the 'Applications' section and press the 'Undeploy' button for the root web application entitled 'Welcome to Tomcat'.
  • Finally, go to the 'Deploy' section and upload ROOT.war.

After successful deployment the list of applications will include a new entry for Infrarch Cloud Office.

First log in

At this point you may start the system for the first time. You can do that by going to http://localhost. The system will initialize for a few seconds and will show the log in screen. You may then enter the default user name and password to log in. The default user name is 'admin' and the default password is 'admin'.

Note:  After logging in, you must immediately change administrator's password.

Configuring Infrarch Cloud Office

Root directories

Infrarch Cloud Office has three main directories, namely:

  • document root, which contains all user files and directories
  • configuration directory, which contains various configurations files, indices, correspondence, etc.
  • backup root, which holds system backups.

After Infrarch Cloud Office is deployed it will initialize default document root, configuraion and backup directories. For security concerns the these directories cannot be set or changed from Infrarch Cloud Office configuration manager but only by an administrator operating the server. The directories are configured from the file named paths.properties in directory $CATALINA_BASE/webapps/ROOT/WEB-INF/classes.

If you have an existing file structure you wish to use, you can set project.root.docs to point to it. You may also wish to change the project.root.backup directory to point to a different physical drive than the drive of the document root directory.

In order to change the document root, configuraion and backup directories you must:

  • invalidate all sessions (from Tomcat Manager)
  • stop Infrarch Cloud Office web application (from Tomcat Manager)
  • edit the file paths.properties
  • start Infrarch Cloud Office.

Security

You should review the security settings and verify that they comply with your needs. The most important such settings are the checks for administrator's IP address and client's IP addresses. When administrator's IP check is on, the administrators will not be able to change system's settings from IP addresses that are outside the local network. When client's IP check is on, only users with IP addresses from the local network and whitelisted IPs will be allowed to connect.

If you choose to turn off client's IP check it is recommended to set the delay after unsuccessful log in to 2-3 seconds.

Backup

You may set the system to automatically backup user data and system files with specified frequency and to a specified location. Parameters that may be set are the number of backups kept, the time to start creating backup, as well as the number of days between backups.

Miscellaneous

Various other settings may be modified and more importantly the default language, maximum file sizes, days to keep file share links, etc.

This concludes the installation process and Infrarch Cloud Office should be fully functional.

Advanced Tomcat configuration

Documentation

These notes give information regarding an installation of Apache Tomcat, which is expected to suffice the practical requirements in most cases. More details and comprehensive information on how to configure Apache Tomcat for more specific use cases and environments is available at the following addresses (depending on which version of Tomcat you are using):

https://tomcat.apache.org/tomcat-8.0-doc/index.html

https://tomcat.apache.org/tomcat-9.0-doc/index.html

Using Apache Portable Runtime (APR)

For better performance you may wish to use the Apache Portable Runtime native library and the APR Connector. APR may be included at Tomcat instalation time or downloaded later from here:

http://tomcat.apache.org/download-native.cgi

Please note that the TLS/SSL configuration of such a connector Connector differs from what is presented here. For more information please refer to the 'SSL Configuration HOW-TO' section of the Apache Tomcat Documentation.

Using Apache Tomcat with Apache HTTP Server

If you already have an Apache HTTP Server installed and wish to continue using it as the front-end, it is possible to use Apache Tomcat together with it. If Tomcat is installed on a separate machine, this will provide an additional security layer between it and the world. Details on how both webservers may be configured to work together can be found here:

https://tomcat.apache.org/connectors-doc/webserver_howto/apache.html

Virtual hosts

You may wish to run more than one separate instance of Infrarch Cloud Office. This may be feasible in cases when business processes must be kept isolated from each other. For information on how to install multiple instances of Infrarch Cloud Office you may refer to the 'Virtual Hosting' section of the Apache Tomcat Documentation.

Installation checklist

Though not complicated the installation requires plenty of steps. It is always possible to miss a step and later waste time tracing problems. To address this an installation checklist has been developed and it is hoped that it would aid the installation process. If you wish, you may download the installation checklist from the link below:

Installation Checklist 160711.pdf