Install OmicSoft v12 on Ubuntu20 for Omicsoft Cloud Computing

From Array Suite Wiki

Jump to: navigation, search


Contents

Build AWS AMI for OmicSoft Cloud Computing

Tips.pngOmicSoft generally recommends using our pre-built Compute AMIs.

OmicSoft Cloud uses customized Ubuntu-based Amazon Machine Images (AMIs) as the template for creating compute instances for running cloud-based analyses. These AMIs require a few key components, including the Oshell engine, packages for transferring data to and from AWS S3 storage, and Docker.

OmicSoft provides default AMIs for cloud computing. Alternatively, users can build their own AMI then follow the configuration steps below. In order to use a specific AMI for cloud computing, one must explicitly specify the preferred AMI in ArrayServer.cfg in the Ami and AmiSnapshot parameters.

If you build your own AMI, the AMI should be built following the instructions below exactly, including the file paths to software tools. Please be aware the OmicSoft support can only provide limited advice on troubleshooting custom AMIs, because of the large number of configuration options that can impact performance.

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.

Tips.png The original 30 GiB size of the cloud computing AMI must be maintained for backwards compatibility.


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

Increase Memory Map Counts

If your cloud jobs use extremely large input files (e.g. hundreds of millions of reads), memory map counts must be increased in order to avoid running out of memory. This is done by setting the vm.max_map_count configuration to a value higher than the 65530 default. The recommended value is 655350.

# Add vm.max_map_count=655350 by editing the following file:
$ sudo vi /etc/sysctl.conf

# Your file should look similar to:
$ sudo cat /etc/sysctl.conf
...
# Increase memory map limits to prevent jobs using
# extremely large files from running out of memmory
vm.max_map_count=655350
...

To check that the new value is persisted on reboot, restart your machine and execute:

$ cat /proc/sys/vm/max_map_count
655350

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 packages

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

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