Palvelut

Ohjeita Singularityn käyttöön

Tältä sivulta löydät ohjeita Singularityn asentamiseen ja sen käyttöön.

Kuinka asennan Singularityn

Voit asentaa Singularityn kahdella eri tavalla:

Tapa 1: asentamalla Singularityn kolmessa vaiheessa:
- asentamalla riippuvuudet
- asentamalla Go-ohjelmointikielen
- lataamalla SingularityCE:n
Tapa 2: Asentamalla valmiiksi buildatun imagen jo olemassa olevien konttien avulla.

Tapa 1: asenna Singularity kolmessa vaiheessa

1. Asenna riippuvuudet:

a. Debian-pohjaiset järjestelmät, kuten Ubuntu:

Komentorivin komennot päivittävät ja asentavat paketteja 'sudo apt-get' avulla, mukaan lukien autoconf, git, wget ja zlib1g-dev.

Komento tekstinä kopiointia varten:

^{sudo apt-get update}
^{sudo apt-get install -y \}
  ^{autoconf \}
  ^{automake \}
  ^{cryptsetup \}
  ^{fuse2fs \}
  ^{git \}
  ^{fuse \}
  ^{libfuse-dev \}
  ^{libseccomp-dev \}
  ^{libtool \}
  ^{pkg-config \}
  ^{runc \}
  ^{squashfs-tools \}
  ^{squashfs-tools-ng \}
  ^{uidmap \}
  ^{wget \}
  ^Zlib1g-dev

b. Ubuntun versiolle 24.04 tai sitä korkeammalle asennetaan lisäksi libsubid headerit seuraavalla komennolla:

^{`sh sudo apt-get install -y libsubid-dev `}

2. Asenna Go:

a. Voit ladata Go:n suoraan Go:n omilta sivuilta osoitteesta: https://go.dev/dl/

b. Vaihtoehtoisesti voit ladata Go:n seuraavilla komennoilla. Vaihda annetut arvot tarvittaessa:

Skripti Go:n asentamiseksi: versio, lataus, purkaminen ja PATH-päivitys.

Komento tekstinä kopiointia varten:

^{export VERSION=1.24.1 OS=linux ARCH=amd64 && \}
^{wget https://dl.google.com/go/go$VERSION.$OS-$ARCH.tar.gz &&}
^\
^{sudo tar -C /usr/local -xzvf go$VERSION.$OS-$ARCH.tar.gz &&}
^\
^{rm go$VERSION.$OS-$ARCH.tar.gz}

^{echo 'export PATH=/usr/local/go/bin:$PATH' >> ~/.bashrc && \}
^{source ~/.bashrc}

3. Lataa SingularityCE

a. Valitse haluttu julkaisu SingularityCE:stä:

https://github.com/sylabs/singularity/releases

b. Tämän jälkeen aja seuraava komento. Kirjoita komentoon halutun version numero:

Shell-skriptin katkelma, joka lataa ja purkaa Singularityn

Komento tekstinä kopiointia varten:

^{export VERSION=4.3.0 && \}
^wget
^{https://github.com/sylabs/singularity/releases/download/v${VER SION}/singularity-ce-${VERSION}.tar.gz && \}
^{tar -xzf singularity-ce-${VERSION}.tar.gz && \}
^{cd singularity-ce-${VERSION}}

i. Käännä SingularityCE lähdekoodi seuraavalla komennolla:

^{./mconfig && \ make -C builddir && \ sudo make -C builddir install}

Voit varmisaa asennuksen onnistumisen ajamalla seuraavan komennon, jolla voi tarkistaa Singularityn version:

^{singularity --version}

Tapa 2: Asenna Singularity valmiiksi buildatun imagen avulla

Singularity on mahdollista asentaa myös jo olemassa olevien konttien avulla.

Löydät Container Libraryn täältä: https://docs.sylabs.io/guides/latest/user-guide/quick_start.html.

Voit ladata kontteja myös Docker hubista: https://hub.docker.com/.

Voit ladata valmiita kontteja ja imageja käyttämällä pull ja build -komentoja.

pull-komentoa käytetään esimerkiksi seuraavanlaisesti (kontin lataaminen kirjastosta):

^{singularity pull library://<NIMI>}

Valmiin Docker imagen lataaminen voi heikentää toistettavuutta, sillä myöhemmin uudelleen ladattaessa image ei välttämättä ole enää sama.

build-komentoa käytetään seuraavanlaisesti:

^{singularity build ubuntu.sif library://ubuntu}

build-komentoa käytettäessä kontin nimi tulee spesifioida (ubuntu.sif yllä). Lataamisen lisäksi build -komennolla voi myös luoda uuden imagen toisen pohjalta tai def-tiedoston pohjalta. Lisää def-tiedostosta alempana.

Huom! Valmiiseen imageen voi lisätä tarpeen mukaan kirjastoja yms kontin def-tiedostoon. Löydät ohjeet ja esimerkin lisäämiseen alta.

Kuinka luon kontin ja imagen

Definition-tiedosto

Definition-tiedostoa (def-tiedosto lyhyesti ilmaistuna) käytetään kontin imagen luomiseen. Def-tiedosto on kätevä etenkin silloin, kun kontin konfiguraatioita halutaan kustomoida eri tarpeiden mukaisesti.

Esimerkki testi def-tiedoston rakenteesta (kuva alhaalla):

Pääteikkuna, jossa näkyy Ubuntu-skriptin rakennusohjeet. Osia ovat environment, post, test ja runscripts.

Def-tiedosto koostuu kahdesta pääosiosta:

Header-osiossa määritellään käyttöjärjestelmä ja konfiguroidaan tarvittavat toiminnot. Headerissa avainsanoja ovat Bootstrap, From ja Stage.

Bootstrap on avainsanoista aina pakollinen ja tulee löytyä jokaisesta def-tiedostosta. Se määrittää bootstrap agentin, jota käytetään pohjalla olevan käyttöjärjestelmän luomiseen. Ylläolevassa esimerkissä image luodaan kirjaston avulla. Image on voidaan luoda myös esimerkiksi Dockerin avulla.
From-avainsanalla määritellään ja tarkennetaan käytetyn bootstrap agentin versio. Yllä olevassa esimerkissä käytetään library agenttia ja tarkemmin Debian kontti.
Muut avainsanat
- Stage avainsanalla tarkoitetaan missä vaiheessa def-tiedostoa käytetään. Kyseisessä esimerkissä tiedostoa käytetään buildaamaan/ajamaan image.

Muut osiot koostuvat kontin toimintoja määrittävistä osioista. Osiot määritellään ensin %-merkillä, johon liitetään osion nimi. Kaikki osiot ovat vaihtoehtoisia ja samaa osiota voi esiintyä tiedoston sisällä useammin kuin kerran.

Lista osioista:

^%setup-osiota käytetään ajamaan osion komennot buildaamisen aikana kontin ulkopuolella host järjestelmässä.
^%files-osiota käytetään kopioimaan tiedostoja hostista eli kontista määränpäähän.
^%environment-osiota käytetään ympäristön muuttujien määrittämiseen ajon aikana.
^%post-osiota käytetään tiedostojen lataamiseen Internetistä, komentojen ajamiseen (esim. pakettien ja päivitysten ajaminen), konfiguraatiotiedostojen kirjoittamiseen, uusien hakemistojen luomiseen ja niin edelleen.
^%runscript-osion sisältö kirjoitetaan sille tarkoitettuun tiedostoon kontin sisällä, mikä ajetaan kontin imagen ajaessa.
^%startscript-osion sisältö kirjoitetaan sille tarkoitettuun tiedostoon buildaamisen aikana.
^%test-osiota käytetään ns. kontin validoimiseen käyttäjän tekemien testien avulla. Tässä osiossa voi haluamillaan menetelmillä testata kontin toiminnallisuuksia.
^%labels-osiota käytetään metadatan lisäämiseen. Data lisätään nimi-arvo pareina.
^%help-osion sisältö kirjoitetaan sille tarkoitetun metadata tiedostoon kontissa buildaamisen aikana (esim. kuvaus kontista tai sen käyttöohjeita).

Kuinka luon imagen

Yleisesti kontit buildataan SIF (singularity image format) -konteiksi, jotka ovat kompressoituja ja muuttumattomia. SIF-kontit ovat hyvä valinta erityisesti teholaskentaa (High Performance Compuling, HPC) käyttäville tutkijoille toistettavuutensa ansiosta.

Imagen voi koota/buildata myös yllä olevan def-tiedoston pohjalta.

Sandbox

Kontin luominen --sandbox flagin kanssa luo imagen muokattavaan hakemistopuuhun, joka vastaa kontin sisäistä tiedostojärjestelmää.

Flagia käytetään build-komennon kanssa esimerkiksi seuraavanlaisesti:
Esimerkissä luodaan alahakemisto _ubuntu/ mistä löytyy Ubuntu käyttöjärjestelmä

^{singularity build --sandbox ubuntu/ library://ubuntu}

Sandboxilla luodulle kontille voi käyttää shell-komentoa, minkä avulla konttia pystyy muokkaamaan ja kehittämään myös myöhemmin.

Sandboxin käyttäminen voi olla helpompaa kuin def-tiedoston käyttäminen, jos käyttäjän pitää itse iteroida joitain osia kuten esim. löytää sopivia kirjastojen versioita. Sandbox imaget soveltuvat siis hyvin kehittämiseen, kun imagen lopullinen muoto ei ole vielä selvillä ja sitä halutaan konfiguroida.

Sandboxin käyttäminen kuitenkin vaikuttaa imagen toistettavuuteen. Def-tiedoston käyttäminen voi siis HPC:ta käyttäville tutkijoille olla parempi vaihtoehto toistettavuuden puolesta.

Fakeroot

Fakeroot ominaisuus mahdollistaa konttien luomisen ja ajamisen ilman root-oikeuksia, jos käyttäjällä ei niitä ole. Lähtökohtaisesti Singularitya käytettäessä root-oikeuksia ei tulisi tarvitakaan.

Fakeroot kuitenkin rajoittaa käyttäjän oikeuksia avata tai muokata tiedostoja ja hakemistoja, joihin käyttäjällä ei ole oikeuksia.

Ominaisuutta käytetään seuraavanlaisesti, esimerkiksi kun konttia buildataan:

^{singularity build -- fakeroot test.sif test.def}

Fakeroot ominaisuutta voi käyttää seuraavien komentojen kanssa:

●    build
●    shell
●    exec
●    run
●    instance start
●    instance build

Imagen luominen scriptille

1. Tehdään script-tiedosto, jos sellaista ei jo ole.

2. Luodaan def-tiedosto imagelle.

Esimerkki definition-tiedostosta, jossa on osiot files ja runscript.

Esimerkki 1 def-tiedoston luomisesta.

Tiedostossa käytetään osioita files ja runscript, kun imagea luodaan script-tiedostoa käyttäen.

Toinen esimerkki def-tiedoston luomisesta

Esimerkki 2 def-tiedoston luomisesta.

Tähän esimerkkiin on lisätty post-osio, jonka avulla voi asentaa tarvittavia paketteja, ohjelmia, ohjelmointikieliä ja muuta tarvittavaa. Pakettien ja ohjelmien versioista voi ladata viimeisimmät versiot spesifioimalla versionumeron niitä ladatessa.

Kuinka käytän imageja

Kun image on luotu tai valmis image ladattu, sen kanssa voi olla vuorovaikutuksessa eri komentoja käyttäen.

Shell

shell-komento avaa terminaaliin uuden komentorivin, jonka kautta konttia voi käyttää ja hallinnoida virtuaalikoneen tavoin. Komentoa käytetään seuraavanlaisesti:

^{singularity shell <tiedoston_nimi>.sif}

Komento avaa seuraavanlaisen tilan (kuva oikealla).

Tilasta poistutaan exit-komentoa käyttäen.

Exec

exec-komennon avulla voidaan ajaa funktio tai komento kontin sisältä ja saada terminaaliin mahdollinen funktion antama tuloste. Jos funktio ottaa parametrin inputtina, se annetaan heti funktion kutsumisen jälkeen.

Komentoa käytetään seuraavanlaisesti:

^{singularity exec <tiedoston_nimi>.sif <funktion_nimi> (parametri)}

Run

run-komentoa käytetään käyttäjän tekemien scriptien (runscripts) ajamiseen.

Komentoa käytetään seuraavanlaisesti:

^{singularity run <tiedoston_nimi>.sif}

Tämän jälkeen scriptiä voi niin sanotusti kutsua pelkkää image tiedoston nimeä käyttäen:

^{./<tiedoston_nimi>.sif}

Komento voi ottaa myös argumentteja exec-komennon tavoin.

Esimerkki run-komennon käyttämisestä, kun komennossa on argumentteja mukana.

Esimerkki alpine-kirjastoa käyttäen (kuva oikealla).

Mahdollisia ongelmatilanteita ja niiden ratkaisuja

päivittyy

Tätä palvelua tarjoaa:

IT-palvelut

Jos tarvitset lisätukea, ota meihin yhteyttä.

Päivitetty: 26.1.2026
Julkaistu: 14.11.2025