Latest revision as of 13:59, 8 June 2024

Singularity CE 3.x (Community Edition)

Esta será a versão utilizada na rede VeRLab/JLab a partir de mar/2022, atualmente instalado nas máquinas a v3.10.x

Documentação oficial Singularity CE v3.x

• https://www.sylabs.io/docs/

User Guide CE v3.10.x

• https://docs.sylabs.io/guides/3.10/user-guide/
• https://docs.sylabs.io/guides/3.10/user-guide/quick_start.html

Adm Guide CE v3.10.x (Apenas para problemas mais específicos de segurança e instalação!)

• https://docs.sylabs.io/guides/3.10/admin-guide/

Definition Files

• https://docs.sylabs.io/guides/3.10/user-guide/definition_files.html
  • Exemplos de Definition Files : https://github.com/sylabs/examples
  • Singularity Definition Files vs. Docker file : https://docs.sylabs.io/guides/3.9/user-guide/singularity_and_docker.html#sec-deffile-vs-dockerfile

IMPORTANTE: Diferença entre os 2 formatos suportados pelo singularity build:

Pasta sandbox: INDICADO PARA FASE DE TESTES E MODIFICAÇÕES no container (instalar pacotes)

• Destinado para desenvolvimento interativo do container, quando ainda precisa fazer testes e não se sabe exatamente as configurações/ferramentas a serem usadas, logo o container pode ter novas instalações e alterações nos pacotes.
• Vantagem: vários arquivos e sub-pastas que são expansíveis automaticamente conforme os pacotes são instalados (opção --writable). O tamanho do disco é expansível conforme disponibilidade de espaço em disco da máquina host.
• Desvantagem: Execução mais lenta, muitos arquivos para copiar de uma máquina para outra e reproduzir o experimento
• writable (ch)root directory called a sandbox for interactive development ( --sandbox option)

Arquivo único, extensão .sif: SOMENTE LEITURA, NÃO é possível editar o container

• Destinado para fase de experimentos em massa (production)
• Vantagem: É uma imagem comprimida, ocupa menos espaço em disco e executa mais rápido que um container equivalente no formato sandbox. Também suporta criptografia
• Desvantagem: Não é possível instalar/modificar pacotes do container. Para instalar/editar algo, tem que transformar em "pasta sandbox".
• compressed read-only Singularity Image File (SIF) format suitable for production (default)

Passo a Passo: Uso do Singularity CE v3.x

Exemplos de interação mais usuais com o container singularity

1. Confirmar se a máquina tem singularity instalado e a versão
2. Solicitar sua pasta de trabalho com seu nome de usuário (storage ou homeLocal)
3. Escrever a "receita" (definition file) do seu container Singularity
4. Criar seu container Singularity no formato "pasta sandbox" usando seu definition file
5. Corrigir o ownership da sua "pasta sandbox"
6. Usar o shell do container em modo --writable --no-home (instalar, modificar e testar)
7. Usar o shell em modo "somente leitura" para testar
8. Usar o shell e montar uma pasta do host
9. Converter um container singularity do formato "pasta sandbox" para o formato .sif (imagem compactada)

1) Conferir se a máquina tem singularity instalado e a versão

   singularity --version

2) Solicitar a criação da sua pasta de trabalho com seu nome de usuário (storage ou homeLocal)

Deve-se solicitar a um gestor da infraestrutura da rede VeRLab/JLab para criar uma pasta com seu nome de usuário e mudar o proprietário da pasta para seu usuário da rede do Verlab e o grupo DomainUsers (gid=513).

Existem duas opções de locais para armazenar sua pasta de containers singularity:

• No serviço de storage da rede, na pasta /srv/forge/fulano/ ou
• Localemente em alguma máquina, na pasta /homeLocal/fulano

2a) Pasta no serviço de storage (/srv/forge):

• Foi escolhido que das máquinas de processamento na rede, apenas EPONA, GHOST e MAGRITTE serão capazes de criar um container.
• Outra restrição é que essa permissão só pode ser executada na pasta /srv/forge
• É importante que cada usuário limpe seus dados de experimentos e testes com frequência, pois não existe uma política de "quotas", assim todos contribuem para para liberar espaço na storage para os demais usuários.

   cd /srv/forge 
   sudo mkdir fulano
   sudo chown -Rv fulano:513 fulano/
   cd /srv/forge/fulano

2b) Pasta no disco local de alguma máquina da rede /homeLocal):

• As máquinas da rede com GPU costumam ter uma partição do disco separada para os usuários ocuparem com dados de experimentos e testes. Essa partição é montada na pasta /homeLocal
• É importante que cada usuário limpe seus dados de experimentos e testes com frequência, pois não existe uma política de "quotas", assim todos contribuem para para liberar espaço em disco para os demais usuários.

   cd /homeLocal
   sudo mkdir fulano
   sudo chown -Rv fulano:513 fulano/
   cd /homeLocal/fulano

3) Escrever a "receita" (definition file) do seu container Singularity

O Definition file é o arquivo que descreve a forma como o Singularity vai criar seu container, qual sistema operacional será usado como base, quais pacotes instalar, criar alguma pasta e etc Na documentação so singularity tem mais explicações sobre a sintaxe e função de cada campo:
Definition Files

• https://docs.sylabs.io/guides/3.10/user-guide/definition_files.html
  • Exemplos de Definition Files : https://github.com/sylabs/examples
  • Singularity Definition Files vs. Docker file : https://docs.sylabs.io/guides/3.9/user-guide/singularity_and_docker.html#sec-deffile-vs-dockerfile

Abaixo um exemplo de definition file (salvo como ubuntu-cuda.def) que tem como base um sistema operacional ubuntu 20.04 e instala os pacotes para executar o cuda:

BootStrap: library
From: ubuntu:20.04

%post
    cd
    apt -y update
    DEBIAN_FRONTEND=noninteractive \
    apt -y install \
    git \
    curl \
    wget \
    zip \
    cmake \
    ninja-build \
    build-essential \
    libboost-program-options-dev \
    libboost-filesystem-dev \
    libboost-graph-dev \
    libboost-system-dev \
    libeigen3-dev \
    libflann-dev \
    libfreeimage-dev \
    libmetis-dev \
    libgoogle-glog-dev \
    libgtest-dev \
    libsqlite3-dev \
    libglew-dev \
    qtbase5-dev \
    libqt5opengl5-dev \
    libcgal-dev \
    libceres-dev
    
    # CUDA Toolkit 11.4 pode ser encontrado em https://developer.nvidia.com/cuda-11-4-0-download-archive
    export PATH=$PATH:/usr/local/cuda/bin
    wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2004/x86_64/cuda-ubuntu2004.pin
    mv cuda-ubuntu2004.pin /etc/apt/preferences.d/cuda-repository-pin-600
    wget https://developer.download.nvidia.com/compute/cuda/11.4.2/local_installers/cuda-repo-ubuntu2004-11-4-local_11.4.2-470.57.02-1_amd64.deb
    dpkg -i cuda-repo-ubuntu2004-11-4-local_11.4.2-470.57.02-1_amd64.deb
    apt-key add /var/cuda-repo-ubuntu2004-11-4-local/7fa2af80.pub
    apt update
    DEBIAN_FRONTEND=noninteractive \
    apt -y install cuda

    wget https://github.com/colmap/colmap/archive/refs/tags/3.9.1.zip
    unzip 3.9.1.zip
    cd colmap-3.9.1
    mkdir build
    cd build
    cmake .. -GNinja -DCMAKE_CUDA_ARCHITECTURES=70
    ninja
    ninja install
    cd

    # limpar cache das instalações
    rm -rf /var/lib/apt/lists/*
    apt-get clean


%environment
   export PATH=$PATH:/usr/local/cuda/bin
   export LC_ALL=C


%labels
    Author Verlab


# To build the container
# $ singularity build --sandbox --fakeroot --fix-perms my-cuda/ ubuntu22-cuda.def

3) Criar seu container Singularity no formato "pasta sandbox" usando seu definition file

O formato sandbox é usado para modificar e instalar pacotes no container

   sudo singularity build --sandbox [pasta_destino] [definition-file.def]

A base usada na construção do container pode ter outras fontes online ou local, veja na documentação.

Alguns exemplos:

Usando o definition file ubuntu22-cuda.def como receita para criar o container

   sudo singularity build --sandbox ubuntu22-cuda ubuntu22-cuda.def

Usando o repositório do docker do ubuntu 20 como base para o container

   sudo singularity build --sandbox my_ubuntu20 docker://index.docker.io/library/ubuntu:20.04

Usando o repositório docker do python 3.8 como base para o container (

   sudo singularity build --sandbox my_ubuntu20_py3 docker://python:3.8-bullseye

4) Corrigir o ownership da sua "pasta sandbox"

Como seu container foi criado usando sudo singularity, o ownership da pasta vai ser root:root

Deve-se pedir para algum gestor da infraestrutura da rede VeRLab/JLab alterar o ownership da pasta para seu_usuario:DomainUsers

a) descobrir o UID do usuário e o GID do grupo DomainUsers com o comando id:

   id nome_usuario

b) mudar o ownership, recursivamente, de todos arquivos da pasta sandbox (-R=recursive, -v=verbose)

   sudo chown -Rv [uid]:513 pasta_sandbox/

5) Usar o shell do container em modo --writable --no-home (instalar, modificar e testar)

Executar seu singularity no formato "pasta sandbox" em "modo escrita" para instalar pacotes.

Também é indicado usar a opção --no-home para não montar a /home/root da máquina host e evitar que os instaladores tentem salvar algo na home da máquina host. ( Link com outras dicas sobre --no-home )

Se o instalador tentar usar a /home/root, deve-se ler a documentação do instalador para optar por pastas alternativas dentro da estrutura do container como /usr/bin, /usr/local, /opt/

   sudo singularity shell --writable --no-home my_container/

• Use sudo somente quando necessário modificar o container com instalação de pacotes e configuração
• Foi escolhido que das máquinas de processamento na rede, apenas EPONA, GHOST e MAGRITTE serão capazes de criar um container e abrir em modo edição.
• Outra restrição é que essa permissão só pode ser executada na pasta /srv/forge

6) Usar o shell em modo "somente leitura" para testar

Executar seu singularity no formato "pasta sandbox" em modo "somente leitura" para testar:

   singularity shell my_container/

Em geral, nesse momento também é necessário montar uma pasta externa ao container para salvar dados e resultados, isso é explicado no pŕoximo item

7) Montar /homeLocal/usuario dentro container para salvar resultados (opção --bind )

O comportamento padrão do SingularityCE é montar as pastas /home/$USER, /tmp, and $PWD da máquina host dentro do container (algumas outras pastas também ).

Para acessar outros diretórios da máquina host dentro do container usa-se a sintaxe

   singularity shell --bind [/absolute/path/host/]:[/absolute/path/inside/container]

O caminho de montagem dentro do container é opcional e se for omitido, é usado o mesmo caminho do host, porém o usuário deve ter permissão para acessar a pasta de montagem. No exemplo mostra como deixar o path /homeLocal/fulano acessível dentro do container em /mnt:

   singularity shell --bind /homeLocal/fulano:/mnt my_container/

Também é possivel combinar as opções do --bind com --writable --no-home, neste caso, o root precisa ter permissão para acessar a pasta de montagem:

   sudo singularity shell --writable --no-home --bind /homeLocal/fulano:/mnt my_container/

• link sobre a opção --bind
• link com outras dicas sobre --bind)

8) Converter um container singularity do formato "pasta sandbox" para o formato .sif (imagem compactada)

Depois de pronta, a máquina container, pode ser convertida do formato "pasta sandbox" para o formato de .sif) isso permite que ela execute mais rápido, reduz o espaço em disco.

O container pronto pode ser armazenado na sua pasta /home/nome_usuario da rede, assim pode ser executada como leitura de qualquer máquina de processamento que o usuário logar.

1) Para converter do formato "pasta sandbox" para o formato .sif. Dicas sobre conversão de formatos das máquinas container:

   sudo singularity build [container_destino] [container_origem]
   sudo singularity build my_container-compact.sif my_container/

Limitar recursos do container (RAM, Core's, network e etc)

É possível criar um arquivo cgroups.toml e limitar (ou medir) recursos usados pelo container. Por exemplo, limitar o uso de RAM para não esgotar os recursos da máquina host.

Segue o texto original e os links com mais informações:

The cgroups (control groups) functionality of the Linux kernel allows you to limit and meter the resources used by a process, or group of processes. Using cgroups you can limit memory and CPU usage. You can also rate limit block IO, network IO, and control access to device nodes.

• https://docs.sylabs.io/guides/3.10/admin-guide/configfiles.html#cgroups-toml

• https://docs.sylabs.io/guides/3.10/admin-guide/configfiles.html

Docker Hub: Usar repositório de Máquinas Container Prontas!

• Docker Hub: várias imagens prontas com ferramentas instaladas

   https://hub.docker.com/

Por exemplo pode-se buscar no google: "docker hub opencv ubuntu", uma das respostas será o repositório

   https://hub.docker.com/r/jjanzic/docker-python3-opencv

Para usar um endereço de imagem docker hub e criar seu container singularity, usa-se o formato docker://REPOSITORIO:TAGS

No caso do repósitório exemplo, ao abrir o link, vai encontrar diversas TAGS listadas na pagina:

   List of available docker tags:
   opencv-4.1.0 (latest branch)
   contrib-opencv-4.1.0 (opencv_contrib branch)
   opencv-4.0.1
   contrib-opencv-4.0.1
   opencv-4.0.0
   contrib-opencv-4.0.0
   opencv-3.4.2
   contrib-opencv-3.4.2
   (...)

Assim para criar o container usando build e copiando do repositório exemplo a tag opencv-4.0.1, tem-se:

   sudo singularity build --sandbox opencv-base docker://jjanzic/docker-python3-opencv:opencv-4.0.1

PIP: Python Package Installer

O Python Package Installer, também conhecido como PIP, é responsável por instalar os pacotes Python criados pela comunidade. Dentro do singularity + moosefs, ele tem um comportamento anômalo, não instalando nas pastas padrão. Tais pastas "padrão" são especificadas diretamente no código-fonte do python, mais precisamente no módulo sys. Faz-se portanto necessário utilizar a flag -t/--target ao instalar os pacotes via pip, apontando para a pasta dist-packages da distribuição utilizada.

pip install <package> -t /usr/local/lib/python2.7/dist-packages/

Links dos Comandos Básicos

https://www.sylabs.io/guides/3.9/user-guide/quick_start.html#interact-with-images

• build: Cria uma imagem para a máquina container

• shell: Executa a imagem da máquina container e permite a interação no prompt do shell

• exec: Executa um comando na máquina container, em segundo plano, e apresenta o resultado no shell da máquina host

• run: Executa ações e scripts configurados no container, como se fosse um executável.

• opção --bind: Permite acessar pastas e arquivos (path) da máquina host dentro da máquina container (outras dicas sobre --bind)

build: Criar uma máquina container

Criar uma máquina container editável (para instalar pacotes)

• Deve-se usar um singularity no formato "pasta sandbox" (estrutura de diretórios). Dicas sobre a opção --sandbox.
• Criar singularity sandbox usando o repositório Ubuntu 18.04 do Docker Hub:

   sudo singularity build --sandbox my_container/ docker://index.docker.io/library/ubuntu:20.04
   sudo singularity build --sandbox my_container/ docker://index.docker.io/library/ubuntu:latest

• Exemplo singularity sandbox usando um repositório qualquer do dockerhub

   sudo singularity build --sandbox my_container/ docker://repository_name:tag

outros exemplos menos usados, pois criam container's não editável

• Criar uma máquina container em formato .img (read-only) a partir de um repositório Docker Hub:

   sudo singularity build my_ubuntu.sif docker://index.docker.io/library/ubuntu:latest

Deve-se usar o formato .sif (writable) a partir de um repositório Docker Hub:

   sudo singularity build my_ubuntu.sif docker://index.docker.io/library/ubuntu:latest

• Converter ou Criar uma máquina container em formato de imagem a partir de uma pasta sandbox:

   sudo singularity build my_ubuntu.sif my_container/

shell: Executar a máquina container e interagir no shell:

• Executar a máquina container no shell, sem salvar modificações feitas na sessão:

   singularity shell my_container/
   singularity shell my_ubuntu.sif/

opção --writable: Permitir alterar o container em formato pasta sandbox:

• Só é possivel alterar um container em formato sandbox, uma boa prática é adicionar a opção --no-home é importante para não ocorrer a montagem automática da /home do root, e evitar que instaladores tentem usar essa pasta para instalação de pacotes.

   sudo singularity shell --writable --no-home my_container/

opção --bind:Montando pastas da máquina host para acessar dentro da máquina container

A pasta do home do usuário é montada automaticamente pelo singularity dentro da máquina container (algumas outras também ), mas se for necessário acessar outra pasta no disco da máquina host, deve-se usar a opção --bind para indicar o caminho (path) a ser usado. O usuário precisa ter permissão de leitura e escrita na pasta da máquina host.

• Executar a máquina container no shell e montar o caminho /homeLocal/fulano da máquina host dentro da máquina container

singularity shell --bind /homeLocal/fulano:/mnt my_container/