Install OmicSoft Server v12 on Windows

This page has been migrated, find the latest information here

Overview

Most of our customers are setting up OmicSoft Server on a Linux machine, which can easily enable HPC cluster and external tool integration. However, OmicSoft Server is much easier to set up on Windows Server, where most dependencies are already part of the operating system.

Prerequisites

OmicSoft Server 12 has been officially validated on Windows Server 2019. While OmicSoft Server should also work on other Windows Server version (2016, 1909, 20H2, 2022 etc.), these versions have not been validated yet and are neither officially supported, nor recommended.

Before installing OmicSoft Server on Windows, you need:

• A valid DNS name pointing to your server IP (e.g. omicsoftserver.example.com). This DNS name must be reachable from all machines where OmicSoft Studio or any Analytic Servers will be installed. The DNS name must also point to a static IP address (if hosting on AWS, an Elastic IP address might be necessary).
• A valid TLS 1.2+ server certificate, including its associated private key, for the above DNS name.
  • The type of the certificate should be the usual one, such as those used for web server (Server Authentication) purposes.
  • The certificate must be signed by a public certificate authority. Self-signed certificates cannot be used.
  • If the server certificate is signed by an internal corporate certification authority, its own root CA certificate must be pre-installed on the server and on all computers where OmicSoft Studio will run.
  • Wildcard certificates (e.g. *.example.com) may be used.
• Ensure common OmicSoft Server firewall requirements are met: OmicSoft Suite IT Requirements.

.NET Framework

OmicSoft Server v12.2 or later targets .NET Framework 4.7.2, so the default .NET Framework version that is being shipped with Windows Server 2019 should be sufficient. However, for older Windows Server versions, installing .NET Framework 4.7.2 may be required. The user must have administrative privileges to install .NET Framework, or the ability to do so before installing OmicSoft Server. The installed .NET Framework version can be determined using the following PowerShell command:

Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full" -Name "Version"

If the registry key is missing, then .NET Framework 4.7.2 (or later) is not installed.

Installing an updated version of .NET Framework will likely require a reboot of the host machine, so make sure you plan for any potential downtime as a result of the upgrade.

Install Server Certificate

Starting with OmicSoft Suite 12, each OmicSoft Server instance requires a TLS certificate to be acquired and properly configured, in order to secure the communication between OmicSoft Studio, Oshell, or Land Explorer clients and the OmicSoft Server instance.

Prerequisites

This step is necessary only if you don't have the certificate in PFX format already. Install OpenSSL v1.1 from https://slproweb.com/products/Win32OpenSSL.html (the version of approx. 63 MB). Any other equivalent tool can be used instead of OpenSSL.

If using the MMC / Manage Computer Certificates add-in to generate a custom certificate request (CRS), the ‘classic’ cryptographic service provider like ‘Microsoft Enhanced Cryptographic Provider v1.0’ (CryptoAPI provider) must be used instead of a newer Cryptography Next Generation (CNG / CAPI2) provider, like ‘Microsoft Software Key Storage Provider’. In MMC / Manage Computer Certificate add-in, when generating the custom certificate request (CRS), the Template should be: '(No template) Legacy key' (instead of '(No template) CNG Key').

See OmicSoft_Server_v12_-_Certificates_Setup for more details.

Certificate Generation

You will need a valid TLS 1.2+ signed server certificate (including the associated private key), for the above DNS name (subject field).

The certificate type must be the usual one, like those used for a web server (purpose: Server Authentication). A wildcard certificate (*.example.com) can be used. The certificate must be signed by a public certificate authority. If the server certificate is signed by an internal corporate certification authority, its own root CA certificate must be pre-installed on the server and all computers where OmicSoft Studio will run. Self-signed certificates are not supported.

The certificate should be in the .pfx (PKCS #12) file format, containing the entire certificate chain, including the private key for the server certificate (other possible file format are .pkcs12 or .p12). Sometimes the certificate is delivered by the signing authority in another format (like .PEM or .CRT), and sometimes, the private key and the intermediate CA certificates are in separate files - make sure you have those too, in addition to the server certificate file. Convert these other formats to .PFX file with a command like this:

 "C:\Program Files\OpenSSL-Win64\bin\openssl.exe" pkcs12 -export -out testserver.pfx -inkey privatekey.pem -in servercert.pem -certfile ca_chain.pem -password pass:....

where

• privatekey.pem should be the private key in PEM format (Base64 encoded DER certificate)
• servercert.pem is the signed server certificate in PEM format
• ca_chain.pem is the additional intermediate CA certificates chain in PEM format

This should be the most common scenario - usually the signing certificate authority does not have the private key (used for the server certificate).

To verify if the .pfx contains the private key, you can use the following command:

$ openssl pkcs12 -info -nocerts -in testserver.pfx

...
Shrouded Keybag: ...
Bag Attributes
localKeyID: ...
Key Attributes: <No Attributes>
Enter PEM pass phrase:
Verifying - Enter PEM pass phrase:
-----BEGIN ENCRYPTED PRIVATE KEY-----
....

where testserver.pfx should be replaced with the actual PFX file name.

Installing the Certificate

Open "Manage User Certificates" (Certmgr.msc).

Important: this should be done for the user account that will be used to run the OmicSoft Server Windows service.

1. Go to Certificates > Current User > Personal Certificates.
2. Right-click on the folder and select "Import".
3. Select the server .pfx file. Enter the password as below and make sure you check the exportable option:

Open the newly imported certificate from Personal\Certificates:

Get the certificate thumbprint from Certificate Details to use it in the CertificateThumbprint setting from ArrayServer.cfg:

Important: Make sure you have established a process to periodically renew and install the renewed certificate when it expires.

Installing OmicSoft Server Service

Updating from Older Array Server Service Versions (11 and earlier) to OmicSoft Server Service 12

OmicSoft Server 12 is incompatible with previous versions and requires a new installer.

If ArrayServerService 11.7 or older is installed, follow these steps to update:

1. Back up your Array Server installation directory, especially ArrayServer.cfg, Default.template, Sample.template and Folders.cfg if present.
2. Run Add/Remove Programs and uninstall Array Server Service
   1. If you receive an Error 1001 during uninstall, download and use the Microsoft Uninstaller - https://support.microsoft.com/en-us/help/17588/windows-fix-problems-that-block-programs-being-installed-or-removed
3. Open Services and check that Array Server Service was removed.
   1. If Array Server Service is still listed, run open a command line window as Administrator, and run the command sc delete ArrayServerService
4. Follow the steps in New Installations to download the newest installer. The new service is "QIAGEN OmicSoft Service."

New Installations

1. Download and save the OmicSoft Server Service Installer in any folder
2. Double click OmicSoftServiceInstaller.msi to install the service. You will be asked to choose where you want this service to be installed (e.g. C:\Program Files\OmicSoft\QIAGEN OmicSoft Service). If installed successfully, OmicSoftServerService.exe, as well as some .dll files, should be in the folder you choose.
3. Update to the latest version
   1. The OmicSoft Server Service installer may not have the latest set of application files, so you should run the updater to retrieve all required files.
   2. Download the latest OmicSoftServiceUpdater.exe file to your OmicSoft Server installation directory (e.g. C:\Program Files\OmicSoft\QIAGEN OmicSoft Service) to ensure that this is up-to-date
   3. In the OmicSoft Server directory, right-click on the file OmicSoftServiceUpdater.exe, and select "Run as administrator".

[back to top]

Configuring OmicSoft Server

Download configuration templates. Unzip and save them in the same folder where your service is installed (e.g. C:\Program Files\OmicSoft\QIAGEN OmicSoft Service).
If you are updating from an older OmicSoft Server installation you can carry over your ArrayServer.cfg, Default.template, Sample.template and Folders.cfg files. However please update ArrayServer.cfg with the properties required for OmicSoft Server v12 by reading through the following section carefully.

The downloaded template contains the ArrayServer.cfg, which is the key configuration file. The following sections and fields are mandatory:

• License section - server license code for your company
• Port2 and Port3 - define the port number for data communication (gRPC and SFTP data transfer) between OmicSoft Studio client and OmicSoft Server. Make sure to open these ports on firewall.
• CertificateThumbprint - specifies the server certificate thumbprint
• MasterServerUrl - identify the DNS name and the gRPC port on which the server can be accessed
• OmicSoft directories
  • BaseDirectory - this will be the working directory of the array server, storing all the raw and possessed data. Depending on the projects, it can take huge amount of disk space.
  • OmicsoftDirectory - This directory can be defined locally or on a network drive. All the reference genomes, gene models, Affymetrix CDF files, log files, etc. are stored in this folder.
  • TempDirectory - This should be a local directory (i.e. NOT a network drive) for fast read and write access. It can take twice the size of an unzipped fastq file in some NGS tasks (we would suggest use a drive with at least 100GB storage).
  • LandDirectory - directory for Land data storage. Depending on the number of Lands installed, this can take several hundred GB.
• Locations of Mono 6 binaries installed on your Oshell instance(s), which are required by jobs started through the server:
  • MonoPath
  • MonoJobPath
  • MonoSgenJobPath
  • MonoSummaryPath
• The [Folder] section defines additional local or network folders monitored and available for access by array server users.

To enable cloud-based NGS analysis with the Array Server Cloud add-on, please follow the instructions from ArrayServer_Configuration_with_Cloud. The following properties must be configured within ArrayServer.cfg.

• General Cloud Preferences
  • [Cloud] section
    • AccessKey
    • SecretKey
    • OmicsoftCloudDirectory
    • Ami
    • AmiSnapshot
  • [CloudFolder] section

• VPC Configuration
  • [Cloud] section
    • InstanceProfileArn
    • SubnetID

For a full list of options, see ArrayServer.cfg for more details. For master-analytic server setup, please read Master Server and Analytic Server for more details.

[back to top]

Start Service

Right click on Computer or This PC (on the desktop, or the windows start menu), then click on Manage to open the Computer Management window. Open Services and Applications > Services and look for "QIAGEN OmicSoft Service".

1. Before starting the service, you should set the QIAGEN OmicSoft Service user account. Right click on "QIAGEN OmicSoft Service | Properties", then go to the Log On tab and select a user account, e.g. "MikeSmith". Note: This user account needs to have access rights to all the network drives required by OmicSoft Server.
2. Mouse right click to start QIAGEN OmicSoft Service. The first time starting the QIAGEN OmicSoft Service may take hours, depending on the sizes of existing projects if it is a server migration.
3. While the service starting is in progress, check the status in ArrayServerService.log in the installation folder (e.g. C:\Program Files\OmicSoft\QIAGEN OmicSoft Service).

[back to top]

Updating OmicSoft Server Service

If you already have the OmicSoft Server Service installed and want to update to the latest release version, please follow these steps:

1. Stop the OmicSoft Server Service. Right click on OmicSoft Server Service in Computer Manage window and click stop (see above).
2. Backup the OmicSoft Server BaseDirectory (listed in ArrayServer.cfg). At a minimum, back up the data in BaseDirectory/Database.
   1. You should also routinely back up ArrayServer.cfg, Sample.template, and Default.template, found in your OmicSoft Server installation directory.
3. Download the latest OmicSoftServiceUpdater.exe file to your OmicSoft Server installation directory (e.g. C:\Program Files\OmicSoft\QIAGEN OmicSoft Service) to ensure that this is up-to-date
4. In the OmicSoft Server directory, right-click on the file OmicSoftServiceUpdater.exe, and select "Run as administrator".
5. Start the service by right-clicking on OmicSoft Server Service in Computer Management window, and click start.

Note: Whenever the OmicSoft Server Service is updated, or configuration files are modified, a service restart is necessary to make the change effective.

[back to top]

Rolling Back OmicSoft Server Service

If you would like to revert your OmicSoft Server installation to a previous version, you can do this by using the archived subfolders.

1. Stop the QIAGEN OmicSoft Service. Right click on QIAGEN OmicSoft Service in the Computer Management | Services window and click stop:

2. Navigate to your QIAGEN OmicSoft Service folder, usually C:\Program Files\OmicSoft\QIAGEN OmicSoft Service, and find the subfolder that corresponds to the date of your previous update:

3. In the subfolder, right-click on OmicSoftServerService.exe, and check the Details tab to confirm the version:

4. Copy the contents of this sub-folder to the main C:\Program Files\OmicSoft\QIAGEN OmicSoft Service folder:

5. Start the QIAGEN OmicSoft Service. In the Computer Management | Services window, right-click QIAGEN OmicSoft Service and click Start:

Uninstall OmicSoft Server Service

This is usually NOT necessary, but just in case one wants to completely remove the old version.

1. Delete the service by running the following command as administrator:

sc delete ""QIAGEN OmicSoft Service"

2. In Windows Control Panel -> Programs -> Programs and Features, uninstall QIAGEN OmicSoft Service.

[back to top]

Command-line Tips (Advanced)

Advanced Windows users may run these commands to manage services:

1. Start Service

net start "QIAGEN OmicSoft Service"

2. Stop Service

net stop "QIAGEN OmicSoft Service"

3. Delete Service

sc delete "QIAGEN OmicSoft Service"

Troubleshooting

Windows could not start the QIAGEN OmicSoft Service (Error 1053: The service did not respond to the start or control request in a timely fashion)

If you see an error message similar to this, you may need to update OmicSoftServiceUpdater.exe.

This can be confirmed by inspecting the ArrayServerService.log file, which will provide more details about the error, such as "Array Server can not load access log database. Message = Unable to load DLL 'SQLite.Interop.dll'". As an example, this message indicates that the SQLite.Interop.dll wasn't retrieved because the OmicSoftServiceUpdater.exe version isn't pulling from the appropriate locations.

• Download the latest OmicSoftServiceUpdater.exe file to your OmicSoft Server installation directory (e.g. C:\Program Files\OmicSoft\QIAGEN OmicSoft Service) to ensure that this is up-to-date
• In the OmicSoft Server directory, right-click on the file OmicSoftServiceUpdater.exe, and select "Run as administrator".

You get a 'Invalid provider type specified' error when OmicSoft Server tries to configure the GRPC endpoint at startup

If you get an error similar to: Array Server Service can not load configuration file. Error message: [12/9/2022 8:15:10 AM]: Error starting the gRpc endpoint at IP: 0.0.0.0, port: 8065, certificate thumbprint: .... : Invalid provider type specified the most likely cause is the cryptographic service provider (CSP) selected (probably by default) when the certificate (and it’s private key) were imported in the Windows certificate store. OmicSoft Server during startup is reading the certificate from the Windows store and is trying to get and convert the private key in a format suitable for it’s internal GRPC service endpoint. The current OmicSoft Server implementation is supporting only 'classic' cryptographic service providers like ‘Microsoft Enhanced Cryptographic Provider v1.0’ (CryptoAPI provider) instead of a newer Cryptography Next Generation (CNG / CAPI2) provider, like ‘Microsoft Software Key Storage Provider’.

See OmicSoft_Server_v12_-_Certificates_Setup for more details and a workaround for this issue.

[back to top]