Install OmicSoft Server v12 on CentOS

From Array Suite Wiki

Jump to: navigation, search
Tips.pngThis page describes the installation steps for OmicSoft Server with OmicSoft Suite v12.1, which will was released in May 2022. If you're using OmicSoft Suite v11.7 or earlier, please visit Install Array Server On CentOS or RedHat.


OmicSoft Server 12 is supported on CentOS Stream 8. Previous CentOS versions, including the recently deprecated CentOS Linux 8, are not officially supported, and so not recommended. OmicSoft recommends using one of our pre-built and pre-configured OmicSoft Server AMIs if you are deploying an OmicSoft Server instance on AWS, for quick, straightforward setup.

However, if you choose to build your own instance or are installing on-premises, you can follow these instructions to configure CentOS Stream 8 to run OmicSoft Server.

Contents

AWS Prerequisites

This section only applies when setting up OmicSoft products on an AWS EC2 instance from scratch. Skip this section if installing OmicSoft products on-premises.

Start a new CentOS Stream 8 instance using an appropriate AWS AMI with the following options:

Connect to the instance using SSH and the centos user.

Required Linux Packages

Before installing any required packages, please ensure there are no broken packages/dependencies on your system. Install the following required packages: 

# Apply existing package updates, including security patches:
$ sudo yum update

# Various utilities:
$ sudo yum install ca-certificates curl unzip wget

# Build tools:
$ sudo yum install git gcc gcc-c++ make cmake

# Dependencies for installing other packages (such as R packages) from source:
$ sudo yum install libcurl-devel libxml2-devel openssl-devel libpng-devel libjpeg-turbo-devel zlib-devel

Install the AWS CLI v1 as described in https://docs.aws.amazon.com/cli/v1/userguide/install-linux.html#install-linux-pip: 

# Prerequisites: Python 3.6+, pip3.
$ sudo yum install python3 python3-pip
 
# Check that pip3 was installed successfully:
$ pip3 --version
pip 20.2.2 from /usr/lib/python3.7/site-packages/pip (python 3.7)

# Install AWS CLI v1
$ sudo pip3 install awscli --upgrade

# Check the AWS CLI was installed successfully:
$ aws --version
aws-cli/1.22.65 Python/3.9.6 Linux/4.18.0-348.12.2.el8_5.x86_64 botocore/1.24.10

Install Mono 6

Install Mono 6.12 from the official repository for CentOS/RHEL 8 (https://www.mono-project.com/download/stable/#download-lin-centos). Installing Mono by compiling it from sources is no longer necessary.

Add the Mono repository to your system: 

$ sudo rpmkeys --import "http://keyserver.ubuntu.com/pks/lookup?op=get&search=0x3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF"
$ sudo su -c 'curl https://download.mono-project.com/repo/centos8-stable.repo | tee /etc/yum.repos.d/mono-centos8-stable.repo'

Install Mono 6 from repository: 

$ sudo yum install mono-complete
  
$ which mono
/usr/bin/mono
   
$ mono --version
Mono JIT compiler version 6.12.0.107 (tarball Wed Dec 9 21:44:58 UTC 2020)
...

Create symlinks for the Mono 6 directories (this is needed for backward compatibility): 

$ sudo mkdir /opt/mono-6.12.0
$ sudo mkdir /opt/mono-6.12.0/bin
$ sudo ln -s /usr/bin/mono /opt/mono-6.12.0/bin/mono
$ sudo ln -s /usr/bin/mono-sgen /opt/mono-6.12.0/bin/mono-sgen
$ sudo ln -s /usr/bin/cert-sync /opt/mono-6.12.0/bin/cert-sync
$ sudo ln -s /usr/bin/certmgr /opt/mono-6.12.0/bin/certmgr

Install libgdiplus

The libgdiplus package should have been already installed alongside Mono: 

$ ldconfig -p | grep libgdiplus
   
libgdiplus.so.0 (libc6,x86-64) => /lib64/libgdiplus.so.0
libgdiplus.so (libc6,x86-64) => /lib64/libgdiplus.so

In the unlikely case that libgdiplus was not installed alongside Mono, follow these steps to install it manually.

Check the Mono configuration file, normally located at /etc/mono/config, and make sure the following entries are present at the end of the file, before the closing </configuration> tag: 

<configuration>
...
    <dllmap dll="gdiplus" target="libgdiplus.so" os="!windows"/>
    <dllmap dll="gdiplus.dll" target="libgdiplus.so" os="!windows"/>
    <dllmap dll="gdi32" target="libgdiplus.so" os="!windows"/>
    <dllmap dll="gdi32.dll" target="libgdiplus.so" os="!windows"/>
    <dllmap dll="gdiplus.dll" target="/lib64/libgdiplus.so.0"/>
</configuration>
If not, add them using: 
$ sudo vi /etc/mono/config

Install SQLite

Install SQLite v3.7.14.1 (2012-10-04) by building it from source: 

# Download SQLite source archive:
$ cd /opt
$ sudo wget -c http://www.sqlite.org/sqlite-autoconf-3071401.tar.gz
$ sudo tar zxvf sqlite-autoconf-3071401.tar.gz
$ sudo mv sqlite-autoconf-3071401 sqlite
$ cd sqlite

# Build and install:
$ sudo ./configure --prefix=/opt/sqlite
$ sudo make
$ sudo make install

# Check SQLite was installed successfully:
$ sudo ./sqlite3 --version

# Clean up:
$ sudo rm /opt/sqlite-autoconf-3071401.tar.gz
$ cd ~

Set ulimit

Increase resource limits for users, as described in Setting_up_ulimit_for_ArrayServer#Change_ulimit.

Install Docker

Install Docker as described at https://docs.docker.com/engine/install/centos/.

Configure Docker to start on boot: https://docs.docker.com/engine/install/linux-postinstall/#configure-docker-to-start-on-boot.

Allow non-root users to run Docker commands (required as part of certain EScripts, for example), as described at https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user.

Install R 4.0.4

Enable Extra Packages for Enterprise Linux (EPEL): 

$ sudo dnf install epel-release

Install R v4.0.4: 

# Install R
$ cd ~
$ export R_VERSION=4.0.4
$ curl -O https://cdn.rstudio.com/r/centos-8/pkgs/R-${R_VERSION}-1-1.x86_64.rpm
$ sudo yum install R-${R_VERSION}-1-1.x86_64.rpm
   
# Create symlinks to ensure R is available on the default system PATH variable
$ sudo rm /usr/local/bin/R
$ sudo ln -s /opt/R/${R_VERSION}/bin/R /usr/local/bin/R
$ sudo rm /usr/local/bin/Rscript
$ sudo ln -s /opt/R/${R_VERSION}/bin/Rscript /usr/local/bin/Rscript
   
$ R --version
R version 4.0.4 (2021-02-15) -- "Lost Library Book"
Copyright (C) 2021 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)
   
R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under the terms of the
GNU General Public License versions 2 or 3.
For more information about these matters see
https://www.gnu.org/licenses/.
   
# Ensure R is available in PATH for the root user
$ sudo vi /etc/sudoers
# Find the 'Defaults secure_path=' configuration
# Append :/usr/local/bin to the secure_path value if not already present
# Save the file and exit
   
$ sudo R --version
R version 4.0.4 (2021-02-15) -- "Lost Library Book"
   
# Start the R REPL in preparation for the next step
$ sudo R

Install the required R packages: 

// R REPL environment:
> if (!requireNamespace("BiocManager", quietly = TRUE))
         install.packages("BiocManager")
// This should allways install the BiocManger version matching the R version.
> packageVersion("BiocManager")
[1] ‘1.30.16’
    
> BiocManager::install("impute")
> packageVersion("impute")
[1] ‘1.64.0’
    
// Required in order to install older versions of other packages (the version of the package itself is not that important):
> install.packages("versions")
> packageVersion("versions")
[1] ‘0.3’
   
> versions::install.versions("samr", '3.0')
> packageVersion("samr")
[1] ‘3.0’
   
> BiocManager::install("limma")
> packageVersion("limma")
[1] ‘3.46.0’
    
> versions::install.versions("Rtsne", "0.15")
> packageVersion("Rtsne")
[1] ‘0.15’
   
// Check if voom is installed:
> library(limma)
> ?voom

> versions::install.versions("askpass", "1.1")
> packageVersion("askpass")
[1] ‘1.1’

> versions::install.versions("openssl", "1.4.4")
// If the above fails with the message "The current version and publication date of openssl could not be detected", try running > install.packages("https://cran.r-project.org/src/contrib/Archive/openssl/openssl_1.4.4.tar.gz", repos=NULL, type="source")
> packageVersion("openssl")
[1] ‘1.4.4’
   
> versions::install.versions("curl", "4.3.2")
// If the above fails with the message "package ‘curl’ is not available for this version of R", try running > install.packages("https://cran.r-project.org/src/contrib/curl_4.3.2.tar.gz", repos=NULL, type="source")
> packageVersion("curl")
[1] ‘4.3.2’
   
> versions::install.versions("httr", "1.4.2")
> packageVersion("httr")
[1] ‘1.4.2’
   
> versions::install.versions("spatstat", "1.64-1")
> packageVersion("spatstat")
[1] ‘1.64.1’
   
> versions::install.versions("uwot", "0.1.11")
> packageVersion("uwot")
[1] ‘0.1.11’
   
> versions::install.versions("Seurat", "3.2.3")
> packageVersion("Seurat")
[1] ‘3.2.3’
   
// Latest locfit version that doesn't require R v4.1:
> versions::install.versions("locfit", "1.5-9.4")
> packageVersion("locfit")
[1] ‘1.5.9.4’
   
// Minimum version required by DESeq2
> versions::install.versions("matrixStats", "0.60.1")
> packageVersion("matrixStats")
[1] ‘0.60.1’
   
> BiocManager::install("DESeq2")
> packageVersion("DESeq2")
[1] ‘1.30.1’
    
> BiocManager::install("edgeR")
> packageVersion("edgeR")
[1] ‘3.32.1’

// Installing "lumi" v2.42.0 fails if attempted on Amazon Linux 2, so feel free to skip it.
> BiocManager::install("lumi")
> packageVersion("lumi")
[1] ‘2.42.0’
    
> versions::install.versions("jpeg", "0.1-9")
> packageVersion("jpeg")
[1] ‘0.1.9’
   
> versions::install.versions("latticeExtra", "0.6-29")
> packageVersion("latticeExtra")
[1] ‘0.6.29’
   
> versions::install.versions("Hmisc", "4.5-0")
> packageVersion("Hmisc")
[1] ‘4.5.0’

Install OmicSoft Applications

Install OmicSoft Server

Open Firewall Ports

The OmicSoftServer machine will need to allow certain connections to occur from OmicSoft Studio as well as to certain sites over the internet.

For a complete list of network related requirements please see: OmicSoft Suite IT Requirements.

Create OmicSoft Server installation directory

$ sudo mkdir /opt/arrayserver
$ cd /opt/arrayserver
$ sudo wget -c https://resources.omicsoft.com/software_update/OmicsoftServiceUpdater.exe
$ sudo touch OmicSoftServer.exe

To run OmicSoft Server as a non-privileged user (centos, not root), that user must be made owner of all OmicSoft-related folders: 

$ sudo chown -R centos:centos /opt/arrayserver/

(in order to avoid having to run everything as sudo)

If the data directories already exist, these need to change ownership, too. 

$ sudo chown -R centos:centos /data

The default paths for the Omicsoft data directories can be found here (also available in the ArrayServer.cfg template- https://resources.omicsoft.com/software/ArrayServer/ArrayServerConfigTemplateV12.zip): 

OmicsoftDirectory=/data/Omicsoft
BaseDirectory=/data/Omicsoft/Server
TempDirectory=/data/Omicsoft/Temp
LandDirectory=/data/Omicsoft/Server/Land

Download and Update Configuration Files

Download configuration template 

$ cd /opt/arrayserver
$ wget https://resources.omicsoft.com/software/ArrayServer/ArrayServerConfigTemplateV12.zip
$ unzip ArrayServerConfigTemplateV12.zip
$ sudo rm ArrayServerConfigTemplateV12.zip

Run Omicsoft Service Updater

If the mono process instance running the Omicsoft Server is started, make sure it is stopped first. 

$ cd /opt/arrayserver

# If not downloaded recently, get the latest version of OmicSoftServiceUpdater: wget -c https://resources.omicsoft.com/software_update/OmicSoftServiceUpdater.exe
$ mono ./OmicsoftServiceUpdater.exe

Update ArrayServer.cfg

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:
  • 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.

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.

Update metadata template files

  • default.template: it defines project level meta data, such as requiring project title, and list organism. Admin can customize the project meta data based on this template file and even enforce controlled vocabulary. For first time setup, the default values we prepared should be good to go. Admin can further customized based on the understanding of default.template wiki article.
  • sample.template: it defines sample level meta data, such as requiring users to fill organism and tissue for each samples in sample registration. Admin can customize the sample meta based on this template file and even enforce controlled vocabulary. For first time setup, the default values we prepared should be good to go. Admin can further customize based on the understanding of sample.template wiki article.

Check Omicsoft Server was installed successfully

$ cd /opt/arrayserver
$ mono ./OmicSoftServer.exe --version
OmicSoftServer version=12.1.X.X

Install Oshell

Create Oshell installation directory

$ sudo mkdir /opt/oshell
$ cd /opt/oshell
$ sudo wget -c https://resources.omicsoft.com/software_update/OmicSoftServiceUpdater.exe
$ sudo touch oshell.exe

To run OmicSoft Server as a non-privileged user (centos, not root), that user must be made owner of all OmicSoft-related folders: 

$ sudo chown -R centos:centos /opt/oshell/

Run Omicsoft Service Updater

$ mono ./OmicSoftServiceUpdater.exe

Check Oshell was installed successfully

$ cd /opt/oshell
$ mono ./oshell.exe --version
OShell version=12.1.X.X

TLS Certificates

Prerequisites

  • DNS name
    • DNS must point to the OmicSoft Server machine (ex.: omicsoftserver.example.com)
    • DNS must be reachable from all machines where OmicSoft Studio/Land Explorer/Oshell and (if applicable) Analytic servers will be installed
    • DNS name must point to a static/fixed IP
    • DNS must have a valid TLS >= 1.2 signed server certificate (including the associated private key)

Make sure that the server is reachable using the DNS name, both from outside the server network, but also from the server machine itself: 

ping omicsoftserver.example.com
Pinging omicsoftserver.example.com [X.XXX.XX.XX] with 32 bytes of data:
Reply from X.XXX.XX.XX: bytes=32 time=230ms TTL=37
...
Ping statistics for 3.128.81.13:
   Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
   Minimum = 230ms, Maximum = 231ms, Average = 230ms
  • TLS certificate
    • The certificate should be in .pfx (PKCS #12) format, containing the entire certificate chain and the private key.
    • You also need the intermediate CA certificates in separate files, so you can import them in the Mono store.

Information on how to obtain all the required files can be found Certificates Setup page.

Set up Certificates

Update Certificate Stores

Update certificate stores: 

$ sudo update-ca-trust

Import certificates from the Linux store into the Mono root CA stores: 

$ cert-sync --user /etc/pki/tls/certs/ca-bundle.crt
$ sudo cert-sync /etc/pki/tls/certs/ca-bundle.crt

Configure intermediate CA certificates for https://resources.omicsoft.com: 

$ certmgr --ssl https://resources.omicsoft.com
$ sudo certmgr --ssl -m https://resources.omicsoft.com

Verify if the machine and user root CA stores have been populated: 

$ certmgr -list -c -m Trust
$ sudo certmgr -list -c -m Trust

Set up the TLS certificate

If you don't have all the required files, please review the Certificates Setup page.

Install the intermediate CA certificate(s)

Intermediate CA can be in the following formats: .PEM, .CRT, .CER.

Import the intermediate CA certificates:

  • the current user intermediate CA store 
$ certmgr -add -c -v CA IntermediateCA1.cer
  • the machine intermediate CA store 
$ sudo certmgr -add -c -v -m CA IntermediateCA1.cer

Verify certificates installation with: 

$ certmgr -list -c CA
$ sudo /opt/mono-6.12.0/bin/certmgr -list -c -m CA
Install the server certificate(s)

Import the server certificate in the machine-level ( -m param. ), personal ('My') store, from the PFX file (that must have also the private key included). The private key password might be needed for this step: 

$ sudo certmgr -add -c -v -p privatekeypassword -m My cert.pfx

Verify if the certificate was properly imported with: 

$ sudo certmgr -list -c -m My

Update Omicsoft server configuration file

Get the server certificate thumbprint that must be set in ArrayServer.cfg using the PFX file: 

$ openssl pkcs12 -in cert.pfx -nodes -passin pass:privatekeypassword | openssl x509 -noout -fingerprint | cut -f2 -d'='

Set/Update the thumbprint in ArrayServer.cfg 

Port2=8065
CertificateThumbprint=B1:9A:...:6D:71
MasterServerUrl=omicsoft.example.com:8065

Start OmicSoft Server 

$ cd /opt/arrayserver/
$ mono ./OmicSoftServer.exe >> ./run.log &
$ & disown -h