Commit 44055a03 authored by Felipe Pina's avatar Felipe Pina
Browse files

Merge branch 'feature/SOMA-4367-update-docs' into 'master'

Adiciona documenteção Guia do Usuário [SOMA-4367]

See merge request !47
parents e03606cd e32a9fcc
Pipeline #35725 passed with stages
in 40 seconds
_build
\ No newline at end of file
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
# Guia do Usuário
## Ferramentas utilizada
O documento é escrito no formato [reStructuredText](https://docutils.sourceforge.io/rst.html) e publicado no [Read the Docs](https://readthedocs.org/).
O build da documentação é feito usando o [Sphinx](https://www.sphinx-doc.org/en/master/index.html). Veja como instalar em [Getting Started with Sphinx](https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html).
## Geração da documentação
Para gerar o Guia do Usuário é preciso instalar o tema [Read the Docs Sphinx Theme](https://github.com/readthedocs/sphinx_rtd_theme/):
```
$ pip install sphinx-rtd-theme
```
Depois basta executar os seguintes comandos:
```
$ cd docs
$ make html
```
Os arquivos serão gerados no diretório `docs/_build`.
@import 'fonts.css';
:root {
--color-primary: #177EE6;
--color-black: #000000;
--color-white: #FFFFFF;
--color-grey-1: #FAFAFA;
--color-grey-2: #E0E0E0;
--color-grey-3: #C7C7C7;
--color-grey-4: #ADADAD;
--color-grey-5: #949494;
--color-grey-6: #7A7A7A;
--color-grey-7: #616161;
--color-grey-8: #474747;
--color-grey-9: #2E2E2E;
--color-grey-10: #141414;
--color-blue-1: #F2F9FF;
--color-blue-2: #CCEDFF;
--color-blue-3: #4DAFFF;
--color-blue-4: #0A3B66;
--color-link-visited: #8C1AE5;
}
body {
font-family: 'Open Sans', sans-serif;
}
h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend {
font-family: 'Open Sans', sans-serif;
color: var(--color-grey-8);
}
.toctree-wrapper {
margin-top: 20px;
}
p, h1, h2, h3, h4, h5, h6{
margin: 0;
padding: 0;
}
p {
font-size: 16px;
line-height: 22px;
margin-bottom: 8px;
}
h1 {
font-weight: 700;
font-size: 40px;
line-height: 42px;
margin-bottom: 20px;
}
h2 {
font-weight: 700;
font-size: 22px;
line-height: 22px;
margin-top: 32px;
padding-bottom: 8px;
}
a {
color: var(--color-primary);
}
a:visited {
color: var(--color-link-visited);
}
a:hover {
text-decoration: underline;
}
.external_link::after {
content:"\f08e";
font-family: "FontAwesome";
font-weight: 900;
margin-left :2px;
font-size: 12px;
vertical-align: bottom;
}
a.download code span:hover{
text-decoration: underline;
}
.wy-side-nav-search {
background-color: var(--color-white);
}
.wy-nav-side {
-webkit-box-shadow: 3px -1px 6px 0px rgba(0,0,0,0.1);
-moz-box-shadow: 3px -1px 6px 0px rgba(0,0,0,0.1);
box-shadow: 3px -1px 6px 0px rgba(0,0,0,0.1);
}
.wy-side-nav-search input[type=text] {
width: 100%;
border-radius: 4px;
border-color: var(--color-grey-3);
font-family: "Open Sans", sans-serif;
font-size: 12px;
}
.wy-nav-top {
background-color: var(--color-white);
color: var(--color-primary);
-webkit-box-shadow: 9px -1px 15px -1px rgba(0,0,0,0.2);
-moz-box-shadow: 9px -1px 15px -1px rgba(0,0,0,0.2);
box-shadow: 9px -1px 15px -1px rgba(0,0,0,0.2);
position: fixed;
top: 0px;
width: 100%;
}
.wy-nav-top a {
color: transparent;
display: inline-block;
width: 150px;
height: 50px;
background: url("../images/soma_logo_h.png");
background-repeat: no-repeat;
background-position: center center;
background-size: 75% 75%;
transform: translateX(-12px);
}
.wy-nav-side {
background: var(--color-white);
}
.wy-side-nav-search>a img.logo, .wy-side-nav-search .wy-dropdown>a img.logo {
height: auto;
width: 150px;
}
.wy-side-nav-search>div.version {
color: var(--color-grey-3);
}
.wy-menu-vertical header, .wy-menu-vertical p.caption {
color: var(--color-grey-8);
font-size: 14px;
margin-top: 12px;
}
.wy-menu-vertical a {
color: var(--color-grey-6);
font-size: 14px;
font-weight: 600;
}
.wy-menu-vertical a:hover {
background-color: transparent;
color: var(--color-primary);
}
.wy-menu-vertical li.on a, .wy-menu-vertical li>a.current {
font-weight: 600;
color: var(--color-primary);
}
.wy-menu-vertical li.toctree-l1.current>a {
border: none;
}
.wy-menu-vertical li.current a {
border: none;
}
.wy-menu-vertical li.toctree-l2 a, .wy-menu-vertical li.toctree-l3 a, .wy-menu-vertical li.toctree-l4 a {
color: var(--color-grey-6);
background-color: var(--color-white);
}
.wy-menu-vertical li.toctree-l2 a:hover, .wy-menu-vertical li.toctree-l3 a:hover, .wy-menu-vertical li.toctree-l4 a:hover {
color: var(--color-primary);
background-color: var(--color-white);
}
.wy-menu-vertical li.toctree-l2.current>a, .wy-menu-vertical li.toctree-l3.current>a, .wy-menu-vertical li.toctree-l4.current>a {
background: white;
color: var(--color-primary);
font-weight: 400;
}
.wy-menu-vertical li.toctree-l2.current>a:hover, .wy-menu-vertical li.toctree-l3.current>a:hover, .wy-menu-vertical li.toctree-l4.current>a:hover {
background: white;
}
.wy-nav-content {
background-color: var(--color-white);
min-height: 100vh;
}
.wy-nav-content-wrap {
background-color: var(--color-grey-2);
}
.fa-minus-square-o:before, .wy-menu-vertical li.on a span.toctree-expand:before, .wy-menu-vertical li.current>a span.toctree-expand:before {
content: "\f106";
}
.fa-plus-square-o:before, .wy-menu-vertical li span.toctree-expand:before {
content: "\f107";
}
.fa-minus-square-o:before, .wy-menu-vertical li.on a span.toctree-expand:before, .wy-menu-vertical li.current>a span.toctree-expand:before, .fa-plus-square-o:before, .wy-menu-vertical li span.toctree-expand:before {
color: var(--color-grey-8);
font-size: 14px;
}
.btn {
background-color: var(--color-primary)!important;
color: var(--color-white)!important;
text-decoration: none!important;
}
.btn:visited {
color: var(--color-white)!important;
}
.btn:hover {
background-color:var(--color-blue-4)!important;
}
footer {
margin-top: 32px;
}
@media only screen and (max-width: 768px) {
/* For mobile phones: */
.wy-nav-content {
margin-top: 62.9375px;
}
}
@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');
\ No newline at end of file
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'SGA REST'
copyright = '2020, Tecgraf PUC-Rio'
author = 'Tecgraf PUC-Rio'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = 'pt_BR'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
html_theme_options = {
'display_version': True,
# 'style_nav_header_background': 'white',
'logo_only': True,
# Toc options
'navigation_depth': 2
}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_css_files = [
'css/custom.css',
]
# html_logo = "_static/images/sga_logo.png"
=========================
Documentação do SGA REST
=========================
Visão Geral
===========
O SGA é o componente de sistemas CSBase responsável por executar e monitorar comandos. Ele pode executar os comandos em uma variedades de tipos de recursos computacionais, indo desde uma única máquina até um cluster. Suporta os ambientes Linux e Microsoft Windows (Cygwin).
Arquitetura
-----------
..
TODO Adicionar uma breve descrição da arquitetura com figuras para ilustrar
O SGA é composto dos seguintes módulos/bibliotecas:
sga-daemon
O módulo principal do SGA. Ele é usando em conjunto com um driver.
sga-driver-posix
Um driver do SGA para executar os comandos localmente em sistemas operacionais compatíveis com POSIX. Testando em Linux e Microsoft Windows via Cygwin.
sga-driver-pbs
Um driver do SGA para executar comandos em clusters TORQUE PBS. Este driver utiliza a biblioteca ``sga-exec``, então é possível executá-lo em um dos nós do cluster ou externamente. Neste último caso o acesso ao cluster será feito via SSH. Testado com a versão 2.5.12 do TORQUE PBS.
sga-driver-slurm
Um driver do SGA para executar comandos em clusters Slurm. Este driver utiliza a biblioteca ``sga-exec``, então é possível executá-lo em um dos nós do cluster ou externamente. Neste último caso o acesso ao cluster será feito via SSH. Testado com a versão 20.02 do Slurm.
sga-exec
Uma biblioteca extensível que permite abstrair como é feita a comunicação -- local ou remota -- entre os drivers e o sistema de execução dos comando.
Ao usar a biblioteca `sga-exec` para desenvolver novos drivers de SGA evite o uso das funções `io.*` e `os.*` da biblioteca padrão de Lua.
Guia de Instalação
==================
Aqui são descritos os requisitos, os passos de instalação e como configurar o SGA.
Requisitos
----------
+ Lua 5.2 (ou mais recente)
+ Lua 5.2 development files (ou mais recente)
+ gcc 4.8.5 (ou mais recente)
+ g++
+ make
+ curl
+ unzip
+ openssl_dev 1.1
+ perl
+ ksh
+ LuaRocks 2.4.2 (ou mais recente)
+ git
**Somente para instalações no Microsoft Windows:** use o próprio Cygwin para gerenciar as dependências, com exceção do LuaRocks, que deve ser instalado conforme instruções em https://luarocks.org/.
Instalação
----------
Baixar do repositório o arquivo ``.tgz`` correspondente à versão a ser instalada, por exemplo usando o comando ``wget``:
.. code-block:: console
$ wget -c https://git.tecgraf.puc-rio.br/csbase-dev/sgarest-daemon/-/archive/X.Y.X/sgarest-daemon-X.Y.X.tar.gz
Substituindo ``X.Y.X`` pelo número da versão desejada.
Extrair o conteúdo do arquivo usando o comando ``tar``:
.. code-block:: console
$ tar -xzf sgarest-daemon-X.Y.X.tar.gz
**Somente para instalações no Microsoft Windows:** execute os seguintes comandos LuaRocks antes de iniciar a instalação:
.. code-block:: console
$ luarocks install xml CC=g++ LD=g++
$ luarocks install luaposix LDFLAGS=-no-undefined
Execute os comandos abaixo para instalar o módulo principal do SGA:
.. code-block:: console
$ luarocks install lua-schema-scm-1.rockspec
$ luarocks make sga-daemon-*.rockspec
Em seguida execute um dos comandos para instalar ao menos um dos drivers:
POSIX
.. code-block:: console
$ luarocks make sga-driver-posix-*.rockspec
PBS (experimental)
.. code-block:: console
$ luarocks make sga-exec-*.rockspec
$ luarocks make sga-driver-pbs-*.rockspec
Slurm (experimental)
.. code-block:: console
$ luarocks make sga-exec-*.rockspec
$ luarocks make sga-driver-slurm-*.rockspec
Instalação local ao usuário corrente
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Para instalar somente para o usuário corrente use a opção ``--local`` nos comandos ``luarocks``.
..
TODO Colocar essa mensagem como nota de roda pé e fazer referencia em todos os trecho com uso de luarocks acima.
Instalação sem conexão com a Internet
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Se a instalação for feita em uma máquina sem acesso a Internet, pode-se pegar as `dependências <http://www.tecgraf.puc-rio.br/ftp_pub/csbase/sga-rest/sga-rocks-2020-03-25.tar.gz>`_, copiá-las e extraí-las para a máquina e ao executar os comandos LuaRocks ``install`` and ``make`` adicionar a opção ``--only-server=caminho_para_dependencias``. Por exemplo:
.. code-block:: console
$ tar -xzf sga-rocks-2020-03-25.tar.gz
$ luarocks install --only-server=$HOME/sga-rocks-2020-03-25 lua-schema-scm-1.rockspec
$ luarocks make --only-server=$HOME/sga-rocks-2020-03-25 sga-daemon-*.rockspec
Instalação usando proxy
^^^^^^^^^^^^^^^^^^^^^^^
Para instações realizadas em máquina usando proxy para conexão à Internet siga as instruções disponóveies em https://github.com/luarocks/luarocks/wiki/LuaRocks-through-a-proxy.
Desinstalação
^^^^^^^^^^^^^
..
TODO Como desistalar o SGA e o LuaRocks -- e Lua se for o caso
Configuração
^^^^^^^^^^^^
A configuração do SGA é feita por arquivos no formato Lua. Abaixo segue exemplo do arquivo ``sgad.cfg.example``:
.. code-block:: lua
csbase_server = "http://localhost:40409"
platform = "Linux26g4"
-- sgad_bind_addr = "127.0.0.1"
sgad_host = "localhost"
sgad_port = 12345
sga_name = "chuva"
status_interval_s = 10
exec_polling_interval_s = 5
register_retry_s = 3
project_root_dir = os.getenv("HOME").."/test/sga-environment/csgrid/projects"
algorithm_root_dir = os.getenv("HOME").."/test/sga-environment/csgrid/algorithms"
runtime_data_dir = (os.getenv("TMPDIR") or "/tmp").."/sgad"
sandbox_root_dir = "/tmp/sgad/sandbox"
driver = "sga.driver.posix"
resources = {
"java",
"lua"
}
extra_config = {
csbase_transfer_name = "ssh-datatransfer",
csbase_csfs_root_dir = "/tmp/csfs_sandbox",
ssh_host = "localhost",
ssh_port = 22,
ssh_user_name = "csgrid",
ssh_private_key_path = "/home/csgrid/.ssh/foo_id_rsa"
}
Segue uma breve descrição das configurações:
csbase_server
URL do servidor CSBase no qual o SGA irá se conectar
platform
Plataforma na qual o SGA está executando
sgad_bind_addr
Endereço de bind do SGA. O valor padrão é 0.0.0.0
sgad_host
Endereço IP ou nome da máquina
sgad_port
Porta do SGA
sga_name
Nome do SGA. Usado para identificar unicamente um SGA. Aceita valores alfanuméricos e os caracters ``_``, ``%`` e ``-``.
status_interval_s
Intervalo, em segundos, de atualização do estado do SGA no servidor CSBase. Coleta informações sobre o ambiente de execução tais como CPU, memória, nós do cluster, etc
exec_polling_interval_s
Intervalo, em segundos, de atualização do estado dos comandos em execução no SGA
register_retry_s
Intervalo, em segundos, entre tentativas de registro no servidor CSBase
project_root_dir
Caminho para o diretório do repositório de projetos do servidor CSBase
algorithm_root_dir
Caminho para o diretório do repositório de algoritmos do servidor CSBase
runtime_data_dir
Caminho para o diretório para armazenar dados de controle do SGA
sandbox_root_dir
Caminho para o diretório de sandbox dos comandos. Cada comando terá sua própria sandbox que será removida após o término da execução. Em ambientes de cluster esse caminho precisar ser o mesmo tando na máquina onde o SGA executa quanto nos nós de execução
driver
Driver do SGA. Os seguintes drivers estão dispoíveis: ``sga.driver.posix``, ``sga.driver.pbs`` e ``sga.driver.slurm``
resources
Lista de recursos disponíveis no SGA. Por exemplo um biblioteca necessária para execução de um comando, ou GPU. A lista é especificada usando tabelas Lua
Configuração de múltiplos SGAs
""""""""""""""""""""""""""""""
Na configuração de múltiplos SGAs é possível definir valores *default* de parâmetros no início do arquivo e sobrescrever esses valores (ou adicionar parâmetros que estão sem *default*) em cada SGA definido. Essa configuração é útil por exemplo quando é necessário gerenciar mais de uma fila de um cluster.
Cada configuração particutar a um SGA deve ser adicionado na chave ``sgas`` do arquivo de configuração, no formato:
.. code-block:: lua
sgas = {
[[
sga_name = valor
parâmetro_1 = valor_1
parâmetro_2 = valor_2
parâmetro_n = valor_n
]],
[[
sga_name = valor
parâmetro_1 = valor_1
]]
}
É aconselhável que cada configuração na chave ``sgas`` defina um valor para ``sga_name``. Se o valor não for definido ele pode ser herdado da configuração padrão, e se mais de uma configuração não definir o ``sga_name``, o mesmo nome poderá ser herdado por múltiplas configurações, gerando erro de configuração duplicada.
É importante não definir o mesmo diretório no parâmetro ``runtime_data_dir`` de cada SGA. Se o diretório for o mesmo, os SGAs precisam executar em máquinas diferentes e o diretório precisa ser local de cada máquina, pois a execução não pode acessar um mesmo diretório ``runtime_data_dir`` a partir de SGAs diferentes.
Exemplo de arquivo de configuração múltipla:
.. code-block:: lua
csbase_server = "http://localhost:40409"
platform = "Linux26g4"
-- sgad_bind_addr = "127.0.0.1"
sgad_host = "localhost"
sgad_port = 12345
sga_name = "chuva"
status_interval_s = 10
exec_polling_interval_s = 5
register_retry_s = 3
project_root_dir = os.getenv("HOME").."/test/sga-environment/csgrid/projects"
algorithm_root_dir = os.getenv("HOME").."/test/sga-environment/csgrid/algorithms"
runtime_data_dir = (os.getenv("TMPDIR") or "/tmp").."/sgad"
sandbox_root_dir = "/tmp/sgad/sandbox"
driver = "sga.driver.posix"
resources = {
"java",
"lua"
}
extra_config = {
csbase_transfer_name = "ssh-datatransfer",
csbase_csfs_root_dir = "/tmp/csfs_sandbox",
ssh_host = "localhost",
ssh_port = 22,
ssh_user_name = "csgrid",
ssh_private_key_path = "/home/csgrid/.ssh/foo_id_rsa"
}
sgas = {
[[
sga_name = "chuva"