Adiciona Guia do Usuário

Versão inicial do Guia do Usuário com o Guia de Instalação/Configuração. [SOMA-4367]

Adiciona Guia do Usuário
Versão inicial do Guia do Usuário com o Guia de Instalação/Configuração. [SOMA-4367]
e32a9fcc · Felipe Pina · e03606cd · e32a9fcc · e32a9fcc · e32a9fcc
Commit e32a9fcc authored May 19, 2020 by Felipe Pina
--- a/docs/.gitignore
+++ b/docs/.gitignore
+_build
\ No newline at end of file
--- a/docs/Makefile
+++ b/docs/Makefile
+# 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)
--- a/docs/README.md
+++ b/docs/README.md
+# 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`.
--- a/docs/_static/css/custom.css
+++ b/docs/_static/css/custom.css
+@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;
+       }
+  }
--- a/docs/_static/css/fonts.css
+++ b/docs/_static/css/fonts.css
+@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap');
+  
\ No newline at end of file
--- a/docs/conf.py
+++ b/docs/conf.py
+# 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"
--- a/docs/index.rst
+++ b/docs/index.rst
+=========================
+ 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"
+			runtime_data_dir = "/tmp/sgad/runtime-chuva"
+		]],