Install OmicSoft Server v12 on Ubuntu 20

From Array Suite Wiki
Tips.png This page describes the installation steps for OmicSoft Server with OmicSoft Suite v12.1, released mid-May 2022. If you're using OmicSoft Suite v11.7 or earlier, please visit Getting Started - OmicSoft Suite V11 and Below.

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 Ubuntu 20.04 to run OmicSoft Server.

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 Ubuntu 20.04 instance using an appropriate AWS AMI with the following options:

Connect to the instance using SSH and the ubuntu user.

Required Linux packages

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

$ sudo apt-get install -f

Install the following required packages: 

# Update package repositories:
$ sudo apt-get update

# Install packages:
$ sudo apt-get install gcc g++ bison make git autoconf libtool automake build-essential gettext cmake python3 curl libtool-bin libgdiplus zlib1g-dev libglib2.0-dev
$ sudo apt-get install libpng-dev libjpeg-dev libtiff5-dev libgif-dev libgs-dev libexif-dev libx11-dev fontconfig
$ sudo apt-get install unzip
$ sudo apt-get install wget

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 apt-get 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 Ubuntu (https://www.mono-project.com/download/stable/#download-lin-ubuntu). Installing Mono by compiling it from sources is no longer necessary.

Add the Mono repository to your system: 

$ sudo apt-get install gnupg ca-certificates
$ sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 3FA7E0328081BFF6A14DA29AA6A19B38D3D831EF
$ echo "deb https://download.mono-project.com/repo/ubuntu stable-focal main" | sudo tee /etc/apt/sources.list.d/mono-official-stable.list
$ sudo apt-get update

Install Mono 6 from repository: 

$ sudo apt-get 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) => /lib/libgdiplus.so.0
libgdiplus.so (libc6,x86-64) => /lib/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="/lib/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 ulimit as described at Setting up ulimit for ArrayServer

Install Docker

Install Docker as described in https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository.

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

The R packages included in the default Ubuntu repositories are often outdated. We’ll install R from the CRAN repository, from source.

To install R on Ubuntu 20.04, follow the steps below:

  • Install the dependencies necessary to add a new repository over HTTPS:
sudo apt install dirmngr gnupg apt-transport-https ca-certificates software-properties-common
sudo apt-get install libreadline-dev
sudo apt-get install libssl-dev

sudo apt-get update
sudo apt-get install gdebi-core
export R_VERSION=4.0.4
curl -O https://cdn.rstudio.com/r/ubuntu-2004/pkgs/r-${R_VERSION}_1_amd64.deb
sudo gdebi r-${R_VERSION}_1_amd64.deb
/opt/R/${R_VERSION}/bin/R --version
sudo ln -s /opt/R/${R_VERSION}/bin/R /usr/local/bin/R
sudo ln -s /opt/R/${R_VERSION}/bin/Rscript /usr/local/bin/Rscript
  • Install the required R packages:
sudo apt-get install libxml2 libxml2-dev
sudo apt-get install libcurl4-openssl-dev
sudo apt-get install libssl-dev
sudo R

// R environment
> if (!requireNamespace("BiocManager", quietly = TRUE))
    install.packages("BiocManager")

// Required in order to install older versions of other packages (the version of the package itself is not that important):
> install.packages("versions")

> BiocManager::install("impute")

> versions::install.versions("samr", "3.0")
> BiocManager::install("limma")

> versions::install.versions("Rtsne", "0.15")
  • Check if voom is installed:
> library(limma)
> ?voom
  • Install the rest of the packages:
> versions::install.versions("askpass", "1.1")
> install.packages("https://cran.r-project.org/src/contrib/Archive/openssl/openssl_1.4.4.tar.gz", repos=NULL, type="source")
> versions::install.versions("curl", "4.3.2")
> versions::install.versions("httr", "1.4.3")

> versions::install.versions("spatstat", "1.64-1")
> versions::install.versions("uwot", "0.1.10")
> versions::install.versions("Seurat", "4.0.3")

> versions::install.versions("locfit", "1.5-9.4")
> versions::install.versions("matrixStats", "0.60.0")
> BiocManager::install("DESeq2")
> BiocManager::install("edgeR")
> BiocManager::install("lumi")

> versions::install.versions("jpeg", "0.1-9")
> versions::install.versions("latticeExtra", "0.6-29")
> versions::install.versions("Hmisc", "4.5-0")

NOTE: OmicSoft Server was tested on Ubuntu 20.04 with the following R package versions: 

> packageVersion('BiocManager')
[1] ‘1.30.18’
> packageVersion('impute')
[1] ‘1.64.0’
> packageVersion('samr')
[1] ‘3.0’
> packageVersion('limma')
[1] ‘3.46.0’
> packageVersion('Rtsne')
[1] ‘0.16’
> packageVersion('openssl')
[1] ‘2.0.1’
> packageVersion('curl')
[1] ‘4.3.2’
> packageVersion('httr')
[1] ‘1.4.3’
> packageVersion('Seurat')
[1] ‘4.0.3’
> packageVersion('DESeq2')
[1] ‘1.30.1’
> packageVersion('edgeR')
[1] ‘3.32.1’
> packageVersion('lumi')
[1] ‘2.42.0’
> packageVersion('Hmisc')
[1] ‘4.5.0’
>  packageVersion('askpass')
[1] ‘1.1’
>  packageVersion('uwot')
[1] ‘0.1.11’
>  packageVersion('locfit')
[1] ‘1.5.9.4’
>  packageVersion('matrixStats')
[1] ‘0.60.0’
>  packageVersion('latticeExtra')
[1] ‘0.6.29’
>  packageVersion('jpeg')
[1] ‘0.1.9’
> packageVersion("spatstat")
[1] ‘2.3.4’

# To exit R, type:
> q()

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 (ubuntu, not root), that user must be made owner of all OmicSoft-related folders: 

$ sudo chown -R ubuntu:ubuntu /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 ubuntu:ubuntu /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 (ubuntu, not root), that user must be made owner of all OmicSoft-related folders: 

$ sudo chown -R ubuntu:ubuntu /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

Configure 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 must be signed by a public certificate authority (no self-signed certificates can be used).
    • 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.

Note: On Windows, 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')

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

Certificates setup

Install certificates in mono store

$ sudo apt-get install ca-certificates -y

Update certificate stores: 

$ sudo update-ca-certificates

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

$ cert-sync --user /etc/ssl/certs/ca-certificates.crt
$ sudo cert-sync /etc/ssl/certs/ca-certificates.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 for server

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 /opt/mono-6.12.0/bin/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 /opt/mono-6.12.0/bin/certmgr -add -c -v -p privatekeypassword -m My cert.pfx

Verify if the certificate was properly imported with: 

$ sudo /opt/mono-6.12.0/bin/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
Retrieved from "https://wiki.arrayserver.com/wiki/index.php?title=Install_OmicSoft_Server_v12_on_Ubuntu_20&oldid=31322"