SD Desktopin ohjelmistoympäristön laajentaminen omilla Apptainer-säiliöillä

Tässä ohjeessa käytämme cPoutaa Apptainer-säiliöiden luomiseen, jotta voimme tuoda uusia ohjelmistoja SD Desktopiin.

Vaiheissa 1 ja 2 kuvataan, miten voit ottaa käyttöön oman Apptainer-ympäristön sisältävän virtuaalikoneen cPoudassa. Tämä ei ole ainoa vaihtoehto, ja jos sinulla on jo Apptainer asennettuna muualla, voit ohittaa nämä vaiheet ja käyttää omaa Apptainer-ympäristöäsi.

Vaiheessa 3 kuvataan yksi tapa rakentaa omia ohjelmistosäiliöitä.

Vaiheessa 4 näytetään, miten säiliö ladataan Altaaseen.

Vaiheessa 5 kuvataan, miten säiliöön asennettuja ohjelmistoja voidaan käyttää SD Desktopissa.

1. Oman Apptainer-työpisteen luominen cPoutaan

Jotta voit hyödyntää kaikkia Apptainerin ominaisuuksia, sitä täytyy käyttää ympäristössä, jossa sinulla on järjestelmänvalvojan käyttöoikeudet. CSC:llä voit saada järjestelmänvalvojan oikeudet cPoudassa toimivissa virtuaalikoneissa. cPoudan käyttäminen rakennusprosessissa tuo mukaan muutamia lisävaiheita: sinun täytyy osata käynnistää ja käyttää virtuaalikoneita cPoudassa. Toisaalta cPoudassa on nopea yhteys Allas-palveluun, jota käytetään valmiiden säiliöiden tuomiseen SD Desktopiin.

Ensimmäiseksi käynnistä virtuaalikone cPoudassa cPoudan käyttöoppaan ohjeiden mukaisesti:

Virtuaalikoneen käynnistäminen cPoudan selainkäyttöliittymällä

sekä esimerkiksi näiden opastusvideoiden avulla:

Virtuaalikoneen käynnistäminen ja siihen yhdistäminen paikalliselta macOS-kannettavalta
Virtuaalikoneen luominen cPoudassa -webinaaritallenne.

Tässä ohjeessa käytämme virtuaalikonetta, joka on käynnistetty seuraavilla asetuksilla:

Flavor: Standard.medium
Instance Boot Source: Image
Image Name: Ubuntu-22.04

2. Singularityn ja Allas-työkalujen asentaminen Ubuntu 22.04 -palvelimelle

Tässä lähdemme tilanteesta, jossa olemme kirjautuneet juuri käynnistetylle virtuaalikoneellemme ensimmäistä kertaa. Valmisteluvaiheina meidän täytyy asentaa virtuaalikoneelle Apptainer uusien ohjelmistosäiliöiden luomista varten sekä allas-tools, jotta voimme ladata luomamme säiliöt Altaaseen.

Singularityn asennus tehdään komennoilla:

sudo apt update
sudo apt install -y software-properties-common
sudo apt-get install apt-utils
sudo add-apt-repository -y ppa:apptainer/ppa
sudo apt update
sudo apt install -y apptainer

Tämän jälkeen Allas-työkalut voidaan asentaa seuraavasti:

sudo apt install python3-pip python3-dev
sudo apt-get install python3-setuptools
sudo pip3 install python-openstackclient
sudo apt install python3-swiftclient
curl https://rclone.org/install.sh | sudo bash
git clone https://github.com/CSCfi/allas-cli-utils

Huomaa, että tämä asennusprosessi tarvitsee tehdä virtuaalikoneelle vain kerran.

3. Apptainer-säiliön luominen

Uusien Apptainer-säiliöiden luomiseen on monia tapoja. Voit luoda säiliön tekemällä sandboxin, johon kirjaudut sisään ja lisäät sisältöä kirjoittamalla asennuskomentoja. Vaihtoehtoisesti voit automatisoida asennusprosessin kokoamalla kaikki komennot ja asetukset Apptainerin definition file -tiedostoon, joka ohjaa asennusprosessia. Yksityiskohtainen kuvaus säiliöiden rakentamisesta löytyy Apptainerin käyttöoppaasta.

Tässä käytämme näiden kahden lähestymistavan yhdistelmää. Luomme ensin yksinkertaisen määritystiedoston avulla uuden säiliö-sandboxin, joka sisältää joukon ohjelmistojen asennukseen tarvittavia työkaluja. Sen jälkeen avaamme komentotulkki-istunnon säiliö-sandboxiin ja teemme varsinaiset ohjelmistoasennukset käsin.

3.1 Määritystiedosto

Avaa ensin uusi tiedosto nimeltä ubuntu_with_inst_tools.def komennolla:

nano ubuntu_with_inst_tools.def

Ja kopioi-liitä uuteen tiedostoon alla olevan esimerkkimääritystiedoston sisältö:

Bootstrap: docker
From: ubuntu:20.04
Stage: build

%environment
export TZ=Europe/Helsinki
export LC_ALL=C
export LC_NUMERIC=en_GB.UTF-8
export PATH="/opt/miniconda/bin:$PATH"

%help
Container based on ubuntu containing miniconda.

%runscript
# sample runscript: bamtools passing all arguments from cli: $@
# exec /opt/miniconda/bin/bamtools "$@"

%post
#commands to help installation processes
ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
apt update
apt install -y wget bzip2 git autoconf automake build-essential 
apt install -y zlib1g-dev pkg-config nano

#install conda
cd /opt
rm -fr miniconda
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh  -O miniconda.sh
bash miniconda.sh -b -p /opt/miniconda
mkdir -p /opt/tools
export PATH="/opt/tools/bin:/opt/miniconda/bin:$PATH"
conda config --add channels bioconda
conda config --add channels conda-forge
conda config --set channel_priority strict

3.2 Sandboxin luominen ja käyttö

Seuraavaksi käytämme tätä määritystiedostoa uuden Apptainer-sandboxin luomiseen

sudo apptainer build --sandbox sd_sandbox_1 ubuntu_with_inst_tools.def

Kun sandbox on valmis, avaamme siihen komentotulkki-istunnon. Valitsin -w mahdollistaa kirjoittamisen sandboxiin:

sudo apptainer shell -w sd_sandbox_1

Nyt olemme Apptainer-sandboxin sisällä, ja voimme aloittaa tarvitsemiemme ohjelmistojen asentamisen. Conda on jo käytettävissä, ja se tarjoaa kätevän tavan asentaa monia ohjelmistotyökaluja. Esimerkiksi seuraavat komennot asentavat bamtoolsin Conda-ympäristöön nimeltä biotools.

conda init bash
bash
conda create -n biotools
conda activate biotools
conda install bamtools

Voisimme käyttää myös tavallisia asennusmenettelyjä Condan sijaan. Esimerkiksi komennon conda install vcftools sijasta voisit asentaa vcftoolsin komennoilla:

cd /opt/tools
git clone https://github.com/vcftools/vcftools
cd vcftools/
autoreconf -i
./configure --prefix=/opt/tools
make
make install

Samtoolsin uusi versio voitaisiin asentaa komennolla:

apt install samtools

Pipiä voidaan käyttää Python-moduulien lisäämiseen:

pip install pyhdfe

Kun olet valmis ohjelmistoasennusten kanssa, voit poistua sandboxista komennolla:

exit

Huomaa: Jos olet käynnistänyt bash-istunnon Conda-asennuksia varten, sinun täytyy antaa kaksi exit-komentoa

3.3 Apptainerin image-tiedoston luominen

Nyt olemme takaisin virtuaalikoneen perusympäristössä. Seuraavaksi muunnetaan sandbox Apptainerin image-tiedostoksi komennolla:

sudo apptainer build sd_tools_1.sif sd_sandbox_1

Tämän jälkeen tiedostolistaus (ls -lh) näyttää, että nykyisessä hakemistossa on sandbox-hakemisto ja Apptainerin image-tiedosto

drwxr-xr-x. 18 root   root   4.0K Sep 27 12:56 sd_sandbox_1
-rwxr-xr-x   1 ubuntu ubuntu 419M Sep 27 13:43 sd_tools_1.sif

Huomaa, että sekä sandboxia että Apptainerin image-tiedostoa voidaan käyttää juuri asentamiemme komentojen suorittamiseen. Voimme esimerkiksi tulostaa samtoolsin ohjeviestin molemmilla alla olevilla komennoilla:

apptainer exec sd_sandbox_1 samtools 
apptainer exec sd_tools_1.sif samtools

4. Säiliön lataaminen Allakseen/SD Connectiin

Jotta Apptainer-säiliötä voidaan käyttää SD Desktopissa, se täytyy salata CSC:n julkisella avaimella ja ladata Altaaseen. Jos haluat käyttää samaa säiliötä myös muissa ympäristöissä, esimerkiksi Puhdissa ja Mahdissa, sinun täytyy ladata Altaaseen myös toinen, salaamaton versio.

Latausprosessissa käytämme vaiheessa 2 asentamiamme Allas-työkaluja, jotka asennettiin hakemistoon $HOME/allas-cli-utils. Lisäämme ensin tämän hakemiston komentopolkuun:

export PATH=${HOME}/allas-cli-utils:${PATH}

Seuraavaksi avaamme yhteyden Altaaseen allas_conf-skriptillä. Huomaa, että sinun täytyy määrittää CSC-käyttäjätunnuksesi valitsimella -u your-csc-account. Tässä oletamme, että käyttäjätunnus on kkayttaj.

source ${HOME}/allas-cli-utils/allas_conf -u kkayttaj

Yllä oleva komento kysyy CSC-käyttäjätunnuksen salasanan ja listaa sitten Allas-projektit, jotka ovat käyttäjätunnuksen käytettävissä. Tässä tapauksessa valitsemme numeron, joka määrittää projektin project_2000123. Tämän jälkeen yhteydet valittuun Allas-projektiin pysyvät aktiivisina seuraavat kahdeksan tuntia.

Nyt voimme käyttää Allasta a-toolsin tai rclonen avulla. Seuraavaksi lataamme juuri luomamme säiliöimagen Altaaseen komennolla:

a-put --sdx sd_tools_1.sif -b 2000123_apptainer_sd -m "SD Compatible. Contains bamtools, samtools and vcftools."

Yllä olevassa komennossa valitsinta --sdx käytetään säiliön salaamiseen CSC:n julkisella avaimella. Salattu säiliö tallennetaan ämpäriin 2000123_apptainer_sd. Tässä ämpärin nimi sisältää projektin numeron (2000123) yksilöllisyyden varmistamiseksi, ja sd ilmaisee, että tämä ämpäri sisältää SD Desktopin kanssa yhteensopivaa dataa. Valitsinta -m käytetään lisäämään kuvausrivi siihen metadataobjektiin, jonka a-put luo.

5. Apptainer-säiliöiden käyttäminen SD Desktopissa

Jotta voit käyttää luomaasi apptainer-säiliötä, sinun täytyy ensin ladata kopio säiliöstä SD Desktopiin Data Gateway -työkalulla. Kirjaudu ensin SD Desktopiin ja yhdistä siihen virtuaalityöpöytään, jota haluat käyttää. Avaa Data Gateway, siirry sitten oikeaan projektiin (project_2000123) ja ämpäriin (2000123_apptainer_sd), ja lataa Apptainerin image-tiedosto (sd_tools_1.sif) SD Desktopiin.

Sen jälkeen avaa Linux-pääte SD Desktopissa. Siirrä päätteessä Apptainer-tiedosto siihen sijaintiin, jossa haluat käyttää sitä. Tässä esimerkissä se voidaan tehdä komennolla:

cp /home/kkayttaj/Projects/SD-connect/project_2000123/2000123_apptainer_sd/sd_tools_1.sif ./

Nyt voisimme suorittaa esimerkiksi säiliöön asennetun samtools-komennon.

apptainer exec sd_tools_1.sif samtools

Yllä oleva komento tulostaa säiliöön asennetun samtoolsin version 1.10 ohjeen. Huomaa, että SD Desktopiin on asennettu myös toinen samtoolsin versio, versio 1.9, joten myös alla oleva komento toimisi, mutta se tulostaisi vanhemman samtools-version ohjeen:

samtools --help

Apptainer-säiliötä käytettäessä kannattaa huomioida, että sillä on oma tiedostojärjestelmänsä, joka on vain luku -tilassa. Tämän staattisen tiedostojärjestelmän lisäksi Apptainer liittää valittuja hakemistoja isäntäjärjestelmästä säiliöympäristöön. Näitä bind mount -liitoksia voidaan käyttää datan tuomiseen säiliöön, ja ne ovat myös ainoita paikkoja, joihin uutta dataa voidaan kirjoittaa.

Oletuksena Apptainer bind mounttaa kotihakemiston (/home/$USER), /tmp-hakemiston ja nykyisen työhakemiston ($PWD) säiliöön ajon aikana. Jos sinun täytyy liittää lisää hakemistoja, ne täytyy määrittää singularityn valitsimella -B source-directory:target-directory.

Esimerkiksi jos meillä on syötetiedosto input_bam.bam nykyisessä työhakemistossa, se on automaattisesti käytettävissä säiliön sisällä suoritettavalle komennolle. Mutta jos tarvitsemme myös toisen syötetiedoston reference.bed, joka sijaitsee hakemistossa /data, meidän täytyy lisätä kyseinen hakemisto bind mountattujen hakemistojen listaan. Esimerkiksi:

apptainer -B /data:/data exec sd_tools_1.sif samtools depth -a -b /data/reference.bed input_bam.bam > result.depth