Singularity

2019-10-02T21:05:09Z

Alancneves:

== Singularity ==

O '''Singularity''' é uma ferramenta para a criação de ''"máquina container"'' (uma espécie de ''"máquina virtual"'') que trás algumas vantagens, quando for rodar experimentos nas máquinas de processamento do Verlab/J:

* Não precisa ser usuário com privilégios root para executar sua ''máquina container'' (apenas para criar) e pode instalar suas dependências de experimento no container sem alterar a ''máquina host''. Isso evita mudanças e instalação de pacotes nas máquinas de processamento e que podem atrapalham experimentos de outros usuários.

* Depois de criar sua ''máquina container'' com todas suas dependências, pode-se usá-la para rodar experimento em diferentes máquinas host que tenham GPU. Isso trás flexibilidade para rodar experimento em máquinas simultaneamente, sem precisar instalar todas dependências novamente em outra ''máquina host''.

* A massa de arquivos de dataset (que geralmente ocupam espaço >=500GB) ficam localmente armazenados na máquina host, assim evita tráfego desnecessário na rede. Geralmente na pasta /homeLocal/nome_do_usuario.

* O usuário deixa na sua pasta home da rede apenas sua máquina container em formato de imagem (que em geral ocupa ~4GB) assim basta logar em uma máquina de processamento para rodar seu experimento.

== Instalação ==
Toda máquina de processamento do Verlab/J (máquinas com GPU) deve ter o Singularity instalado e não precisam ter pacotes específicos de software como ROS, cuda, tensorflow.

A equipe de rede é responsável por manter máquinas locais e máquinas de processamento disponíveis para executar o singularity. Foi escolhido que o sigularity estará disponível apenas nas máquinas com GPU Nvidia, assim confira a lista de máquinas na [https://www.verlab.dcc.ufmg.br/restrict-area/ área restrita] do site do verlab:

=== Máquinas locais com GPU Nvidia ===
* Instalar o Singularity em toda máquina host com GPU (máquina de processamento)
* Criar a pasta <code>/homeLocal</code> em toda máquina host. Essa pasta deve dar permissão para qualquer usuários criarem e modificarem suas máquinas container.
* Configurar o comando <code> $sudo singularity ... </code> de modo que todo usuário possa rodá-lo dentro da pasta <code>/homeLocal</code>, sem necessitar de senha root

=== Máquinas de processamento da rede com GPU Nvidia e acesso ao /srv/forge e /srv/storage/singularity/forge ===
* Foi escolhido que das máquinas de processamento na rede, apenas '''PROC2 e ESCHER''' serão capazes de criar um container e abrir em modo edição com '''<code> $sudo singularity shell --writable... </code>'''. Uma segunda restrição é que essa permissão só pode ser executada na pasta <code>'''/srv/forge'''</code>
* Configurar a montagem da pasta <code>/srv/forge</code> nas máquinas PROC2 e ESCHER e configurar a montagem das mesmas para que o comando <code> $sudo singularity ... </code> possa ser executado por qualquer usuário, sem necessitar de permissão root
* Para executar o container sem modo de edição ('''<code>$singularity shell...</code>'''), a pasta <code>/srv/forge</code> é espelhada em <code>proc2:/srv/storage/singularity/forge$</code> e <code>escher:/srv/storage/singularity/forge$</code>

=== PIP ===
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.

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

== IMPORTANTE: Diferença entre os 3 formatos criados pelo <code>build</code>: ==

==== Arquivo único, extensão <code>'''.simg'''</code>: NÃO é possivel editar container ====
* Destinado para fase de experimentos em massa (produção)
* Vantagem: Em geral, ocupa menos espaço e executa mais rápido que um container equivalente no formato '''.img'''. Indicado para produção, versão final de experimentos.
* Desvantagem: Não pode-se fazer modificação no container. Para Instalar algo, tem que transformar em '''.img''' ou '''"pasta sandbox"'''.
* (single file) compressed read-only squashfs file system suitable for production (default)

==== Arquivo único, extensão <code>'''.img'''</code>: NÃO indicado para editar o container, apesar de possível com limitação de espaço ====
* Destinado para a fase de desenvolvimento, mas com container sofrendo poucas alterações.
* Vantagem: Em geral, ocupa menos espaço e executa mais rápido que um container equivalente no formato "pasta sandbox". E ainda pode-se instalar pacotes (opção --writable), porém tem limitação de espaço em disco.
* Desvantagem: O disco tem tamanho fixo, então é possível fazer modificações e instalações com opção --writable, mas se não couber no disco, o mesmo tem que ser expandido manualmente com [https://sylabs.io/guides/2.5/user-guide/appendix.html#image-expand image.expand --size]
*(single file): writable ext3 file system suitable for interactive development ( --writable option )

==== '''Pasta Sandbox''' <code>sandbox directory </code>: INDICADO PARA EDITAR, sem limitações de espaço significativas ====
* Destinado para desenvolvimento inicial do container, quando ainda não se sabe exatamente as configurações e ferramentas a serem usadas, logo o container ainda sofre muitas alterações.
* Vantagem: vários arquivos e sub-pastas que são expansíveis automaticamente conforme vai-se instalando pacotes (opção --writable). O tamanho do disco é expansível conforme disponibilidade da máquina host.
* Desvantagem: Mais lento dos formatos para execução!
* (many files and sub-folders): writable (ch)root directory called a sandbox for interactive development ( --sandbox option)

== Regras de bom uso dos recursos ==

*Cada usuário deve criar uma pasta com seu nome de usuário dentro das pastas de uso comum (<code> /homeLocal/fulano ou /srv/forge/fulano ou /srv/storage/datasets </code>) e usá-la para seus arquivos. Assim fica organizado e facilita identificar quem são os donos dos containers ou datasets.

* A máquina container para rodar os experimentos deve estar em formato de imagem para rodar mais rápido (<code>.img</code> ou <code>.simg</code>). Porém, enquanto estiver em teste e instalando pacotes, ela deve ser uma "pasta sandbox".

* Usuários '''não''' devem deixar o dataset dentro da sua pasta '''home na rede'''. Os datasets são muitos arquivos que vão ser acessados durante o experimento e que seu tamanho total, em geral, é >=500GB. Pois isso aumenta o tráfego na rede desnecessáriamente. Os datasets devem ser armazenados numa pasta local do computador com o nome do usuário ou no servidor de storage (usando uma pasta com o nome do usuário).
** Por exemplo, para o login "fulano" '''não usar''' <code> /home/fulano/dataset </code> mas sim:
** <code> /homeLocal/fulano/dataset </code>
** <code> /srv/storage/datasets/fulano/ </code>

* <del>Cada usuário deve criar/preparar sua máquina container em uma '''pasta local''' e executá-la em ''"modo edição" e como "pasta sandbox" (<code>--writable</code>)'' para instalar os pacotes e dependências para seus experimentos. Por exemplo, usar a pasta local <code> /homeLocal/fulano/my_container </code>. Depois de pronta, a máquina container, pode ser convertida para o formato de imagem (<code>.img</code> ou <code>.simg</code>) e ser ser armazenado na pasta home da rede, assim pode ser executada como leitura de qualquer máquina de processamento que o usuário logar.</del>

== Passo a Passo: caso de uso do Singularity ==

==== Criar sua máquina container em "modo edição" e no formato "pasta sandbox" ( para instalar os pacotes e dependências para seus experimentos). ====

1) Criar sua pasta de usuario em <code> /srv/forge/fulano/ </code> ou <code>/homeLocal/fulano </code> :
cd /srv/forge
mkdir fulano
cd /srv/forge/fulano

cd /homeLocal
mkdir fulano
cd /homeLocal/fulano

2) criar seu container singularity no formato "pasta sandbox" para ser possível instalar pacotes:

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

3) executar seu container singularity em modo edição para instalar pacotes:
sudo singularity shell --writable my_container/

Depois de pronta, a máquina container, pode ser convertida para o formato de imagem (<code>.img</code> ou <code>.simg</code>) e ser ser armazenado na pasta home da rede, assim pode ser executada como leitura de qualquer máquina de processamento que o usuário logar.

* Use <code>sudo</code> somente quando necessário (e.g., instalação de pacotes e configuração). Quando for rodar o container para experimentos, não será necessário invocar o singularity com permissão <code>sudo</code>.

singularity shell my_container/

==== Converter uma máquina container container do formato '''"pasta sandbox"''' para o formato '''<code>.simg</code>''' ====
* Para converter do formato '''"pasta sandbox"''' para o formato '''<code>.simg</code>'''. [https://www.sylabs.io/guides/2.5.1/user-guide/quick_start.html#converting-images-from-one-format-to-another Dicas sobre conversão de formatos das máquinas container]:

sudo singularity build my_ubuntu.simg my_container/

== Links para aprender Singularity ==

==== Documentação oficial ====

* https://www.sylabs.io/docs/ (atual, desde julho/2018)

* https://singularity.lbl.gov/docs-docker (verãos antiga)

==== More details about the different build options and best practices, read singularity flow: ====

https://sylabs.io/guides/2.5/user-guide/introduction.html#the-singularity-usage-workflow

== Docker Hub: 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 <code>build</code> e copiando do repositório exemplo a tag <code>opencv-4.0.1</code>, tem-se:

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

== Alguns Comandos Básicos ==
https://www.sylabs.io/guides/2.5.1/user-guide/quick_start.html#interact-with-images

* <code>[https://www.sylabs.io/guides/2.5.1/user-guide/build_a_container.html#build-a-container '''build''']</code>: Cria uma imagem para a máquina container [http://singularity.lbl.gov/docs-build '''old link''']

* <code> [https://www.sylabs.io/guides/2.5.1/user-guide/quick_start.html#shell '''shell''']</code>: Executa a máquina container no prompt do shell [http://singularity.lbl.gov/docs-shell '''old link''']

* <code>[https://www.sylabs.io/guides/2.5.1/user-guide/quick_start.html#executing-commands '''exec''']</code>: Executa um comando dentro do shell da máquina container, em segundo plano, e apresenta o resultado no shell da máquina host [http://singularity.lbl.gov/docs-exec '''old link''']

* <code>[https://www.sylabs.io/guides/2.5.1/user-guide/quick_start.html#running-a-container '''run''']</code>: Executa ações e scripts configurados no container, como se fosse um executável. [http://singularity.lbl.gov/docs-run '''old link''']

* <code>[http://singularity.lbl.gov/docs-pull '''pull''']</code>: ??? Copia um container de um repositório, pasta sandbox ou imagem pronta ???

== <code>'''build'''</code>: 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). [https://www.sylabs.io/guides/2.5.1/user-guide/quick_start.html#sandbox-directory Dicas sobre a opção <code>--sandbox</code>].
* Criar singularity sandbox usando o repositório Ubuntu 18.04 do Docker Hub:

<code>sudo singularity build --sandbox my_container/ docker://index.docker.io/library/ubuntu:18.04</code>

<code> sudo singularity build --sandbox my_container/ docker://index.docker.io/library/ubuntu:latest </code>

* Exemplo singularity sandbox usando um repositório qualquer do dockerhub
<code> sudo singularity build --sandbox my_container/ docker://repository_name:tag </code>

==== outros exemplos menos usados, pois criam container's com limitação de edição ou não editável ====
* Criar uma máquina container em formato <code>.img</code> (read-only) a partir de um repositório Docker Hub:
<code> sudo singularity build my_ubuntu.img docker://index.docker.io/library/ubuntu:latest </code>

Deve-se usar o formato <code>.img</code> (writable) a partir de um repositório Docker Hub:
<code> sudo singularity build --writable my_ubuntu.img docker://index.docker.io/library/ubuntu:latest </code>

* Para aumentar o tamanho do disco no container formato <code>.img</code> pode-se utilizar o comando [https://sylabs.io/guides/2.5/user-guide/appendix.html#image-expand <code>singularity image.expand --size XXX</code> ]
singularity image.expand my_test.img # Specify a size for an operation in MiB, i.e. 1024*1024B (default 768MiB)
singularity image.expand --size 500 my_test.img # expand size of 500 MiB

* Converter ou Criar uma máquina container em formato de imagem a partir de uma pasta sandbox: ([https://www.sylabs.io/guides/2.5.1/user-guide/quick_start.html#converting-images-from-one-format-to-another Dicas sobre conversão de formatos das máquinas container]

<code>sudo singularity build my_ubuntu.simg my_container/</code>

* Criar uma máquina container em formato <code>.simg</code> (read-only) a partir de um repositório Docker Hub:
<code> singularity build lolcow.simg docker://godlovedc/lolcow </code>

== Executar a máquina container sandbox no shell para instalar pacotes: ==

* TODO: Como fazer na homeLocal e como fazer na proc2:/srv/forge

<code>sudo singularity shell --writable my_container/</code>

== Executar a máquina container no shell: ==

You can make changes to the container (assuming you have the proper permissions to do so) but those changes will disappear as soon as you exit. To make your changes persistent across sessions, use the --writable option. It’s also a good practice to shell into your container as root to ensure you have permissions to write where you like.

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

<code>singularity shell my_container/</code>

<code>singularity shell my_ubuntu.img/</code>

* para algum teste de configuração ou instalação de pacote temporário
<code>sudo singularity shell my_ubuntu.img/</code>

* Executar a máquina container no shell, salvando as modificações da sessão ao sair do container. usar opção --writable ([https://singularity.lbl.gov/docs-flow#writable-image Dicas sobre a opção <code>--writable</code>])

<code>sudo singularity shell --writable my_container/</code> - para instalação de pacotes / configuração

<code>singularity shell --writable my_container/</code> - para a execução de experimentos

==== Exemplos com exec ====

Roomba

2018-10-01T15:20:07Z

Alancneves: Created page with "=== Roomba IRobot Create 4400 === Mais informações em: https://fccid.io/UFE4400/User-Manual/USERS-MANUAL-1-732887.pdf"

=== Roomba IRobot Create 4400 ===

Mais informações em:
https://fccid.io/UFE4400/User-Manual/USERS-MANUAL-1-732887.pdf

Virtualenv

2018-03-08T20:04:51Z

Alancneves:

O '''virtualenv''' é uma ferramenta para a criação de ambientes de '''python''' isolados. Isso permite a utilização de pacotes com versões distintas bem como diferentes versões de python.

== Instalação ==
Inicialmente, verifique se o sistema possui o '''pip'''. Estando no terminal, digite:

<code>$ pip -V</code>

Se o pip não estiver instalado faça: 
<code>
$ [sudo] apt-get install python-pip

$ [sudo] pip install virtualenv
</code>

== Criando um ambiente ==
Para criar um ambiente virtual isolado, faça:

<code>
$ virtualenv <pasta>
</code>

Uma pasta será criada como o nome especificado, com as subpastas ''bin, include, lib e local''.

Virtualenv

2018-03-08T19:56:41Z

Alancneves:

Virtualenv

2018-03-08T19:53:15Z

Alancneves: Created page with "O '''virtualenv''' é uma ferramenta para a criação de ambientes de '''python''' isolados. Isso permite a utilização de pacotes com versões distintas bem como diferentes..."

VeRLab Wiki - User contributions [en]

Singularity

Roomba

Virtualenv

Virtualenv

Virtualenv