Install OmicSoft Server v12 on CentOS
From Array Suite Wiki

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:
- AMI ID: Find the corresponding image ID for your AWS region here: https://www.centos.org/download/aws-images/#centos-amazon-ami-images.
- Architecture: x86 (64-bit)
- Instance type: See Hardware / Software requirements for Array Server#Hardware_Requirements
- Auto-assign Public IP: Enabled
- Storage: A root volume of type General Purpose SSD - gp3. For the size of the volume, see OmicSoft Server Hardware requirements.
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.
- General Cloud Preferences
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
- Install Server v12
- Using ServerAmiRecommendation Template
- Using AWSPrerequisites Template
- Using RequiredLinuxPackages Template
- Using InstallAwsCliV1 Template
- Using InstallMono6Rpm Template
- Using InstallMono6Repo Template
- Using CreateMono6Symlinks Template
- Using CheckLibgdiplus Template
- Using InstallSqlite Template
- Using InstallR404Rpm Template
- Using InstallOmicSoftServer Template
- Using ConfigArrayServerv12 Template
- Using InstallOshellV12 Template
- Using CertificatePrerequisites Template
- Using UpdateCertificateStores Template
- Using CertificateSetup Template