diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..9c5f57827018f6a0435036d9515314e34604b9fe --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +_build \ No newline at end of file diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000000000000000000000000000000000000..d4bb2cbb9eddb1bb1b4f366623044af8e4830919 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# 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) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000000000000000000000000000000000..efbf38f8202388fa7d9f4b5789c3111d65247b27 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,24 @@ +# 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`. diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 0000000000000000000000000000000000000000..4e5badf8dba44c9e1523148bc9ca1c8097126803 --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,239 @@ +@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; + } + } diff --git a/docs/_static/css/fonts.css b/docs/_static/css/fonts.css new file mode 100644 index 0000000000000000000000000000000000000000..80b3f238fe1f89974b7cf374d31cc3b74d866ce8 --- /dev/null +++ b/docs/_static/css/fonts.css @@ -0,0 +1,2 @@ +@import url('https://fonts.googleapis.com/css?family=Open+Sans&display=swap'); + \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000000000000000000000000000000000000..07d702ef486c052f22019b8b140a20029e5d9b1e --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,80 @@ +# 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" diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..4209e914a1c1dde619c1748f03e65791cf2dec61 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,408 @@ +========================= + 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 `_, 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" + ]], + [[ + sga_name = "temporal" + platform = "Linux44_64" + runtime_data_dir = "/tmp/sgad/runtime-temporal" + ]], + sga_name = "garoa" + platform = "Linux64e5" + runtime_data_dir = "/tmp/sgad/runtime-garoa" + ]] + } + +Drivers +""""""" + +Os driver do SGA são responsáveis por acessar o recurso oferecidos pelo SGA. Eles devem ser capazes de executar e monitor comandos se comunicando diretamente com o gerenciador do recurso. Atualmente 3 drivers estão disponíveis: ``sga.driver.posix``, ``sga.driver.pbs`` e ``sga.driver.slurm``. OS drivers podem ter configurações específicas e devem ser informadas na chave ``driver_config``. + +Segue breve descrição de cada driver, com exemplos de configurações: + +sga.driver.posix + Driver para gerencia de comandos usando sistemas operacionais compatíveis com POSIX. Não possui configurações específicas +sga.driver.pbs + Driver para gerencia de comandos em clusters através do TORQUE PBS. Testado com a versåo `2.5.12 `_. As seguintes configurações estão disponíveis: + + init_dir + Diretório de trabalhado para de execução dos comandos. Recomendado usar o valor ``os.getenv("PWD")`` (qsub -d) + queue + Fila de execução do job. Um SGA apenas gerencia uma única fila. Para gerenciar múltiplas filas é necessário utilizar múltiplos SGAs (qsub -q) + allow_proxy_user + Ativa o uso do ``proxy user``, fazendo que os comandos sejam executados no cluster usando o mesmo usuário que fez a submissão no servidor CSBase. O valor padrão é ``false``. (qsub -P) + + .. code-block:: lua + + driver = "sga.driver.pbs" + driver_config = { + init_dir = os.getenv("HOME").."/forecast", + queue = "weather", + allow_proxy_user = false, + } + +sga.driver.slurm + Driver para gerencia de comandos em clusters através do Slurm. Testado com a versão `20.02 `_. As seguintes configurações estão disponíveis: + + init_dir + Diretório de trabalhado para de execução dos comandos. . Recomendado usar o valor ``os.getenv("PWD")`` (sbatch -D) + queue + Fila de execução do job. b. Um SGA apenas gerencia uma única fila. Para gerenciar múltiplas filas é necessário utilizar múltiplos SGA (sbatch -p) + allow_proxy_user + Ativa o uso do ``proxy user``, fazendo que os comandos sejam executados no cluster usando o mesmo usuário que fez a submissão no servidor CSBase. O valor padrão é ``false``. (sbatch --uid) + + .. code-block:: lua + + driver = "sga.driver.slurm" + driver_config = { + init_dir = os.getenv("HOME").."/forecast", + queue = "weather", + allow_proxy_user = true, + } + + +Drivers que usam a biblioteca ``sga-exec`` podem configurá-la para fazer o dispáro remoto de comandos usando o protoco SSH. Segue trecho da configuração: + +.. code-block:: lua + + driver_config = { + exec_driver = "sga.exec.ssh", + exec_config = { + host = "username@hostname", + port = 22, + } + } + +Lembrando que é necessårio ativar a autenticação por chave publica, sem senha, do usuário na máquina. Veja `Public Key authentication for SSH `_ para mais detalhes. + +Mecanismos de transferências +"""""""""""""""""""""""""""" + +O SGA permite o uso de mecanismos de trasnfêrencias para ambiente onde a área de projeto do servidor CSBase não está disponível na máquina onde o SGA está executando. Observe que o uso de mecanismos de transferência adiciona um atraso no início/término da execução do comando, já que os binários do algoritmo e os arquivos de entrada e saída precisam ser copiados da área de projetos para a área de transferência do SGA. + +Atualmente existe apenas o mecanismo de transferência ``ssh-datatransfer`` que usa o protocolo SSH/SCP para fazer a cópia e ele tem os seguintes requisitos: + +* servidor CSBase deve ter esse mecanismo instalado +* máquina onde o SGA executa deve ser acesível via SSH +* acesso por chave pública, sem senha, configurado para o usuário configurado. Veja `Public Key authentication for SSH `_ para mais detalhes + +Para configurar deve-se adicionar a chave ``extra_config`` ao arquivo de configuração. As configurações disponíveis são: + +csbase_transfer_name + Nome do mecanismo de tranferência, deve ser ``"ssh-datatransfer"`` +csbase_csfs_root_dir + Diretório, na máquina onde o SGA executa, da área de transferencia +ssh_host + Nome da máquina onde o SGA executao +ssh_port + Porta do servidor SSH da máquina onde o SGA executa +ssh_user_name + Usuário que executa o SGA +ssh_private_key_path + Caminho, **no servidor CSBase**, para a chave privado do usuário +ssh_user_pass + Senha do usuário que executa o SGA (é recomendado o uso de chave privada para fazer a autenticação) + +Segue exemplo de configuração: + +.. code-block:: lua + + driver = "sga.driver.posix" + extra_config = { + csbase_transfer_name = "ssh-datatransfer", + csbase_csfs_root_dir = "/tmp/csfs_sandbox", + ssh_host = "remote-server", + ssh_port = 22, + ssh_user_name = "user", + ssh_private_key_path = "/home/csgrid/.ssh/csgrid_id_rsa" + } + +Execução +======== + +Para iniciar o SGA execute o seguinte comando em um shell/terminal: + +.. code-block:: console + + $ ./sgad sgad.cfg + + +Já para executar um SGAs que utiliza a configuração múltipla + +.. code-block:: console + + $ ./sgad.sh sgad.cfg --sga_name garoa + +Para visualizar as propriedades processadas pelo SGA existe a flag ``--debug``: + +.. code-block:: console + + $ ./sgad.sh sgad.cfg --sga_name garoa --debug + +Verificando a instalação +------------------------ + +Em breve. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000000000000000000000000000000000000..2119f51099bf37e4fdb6071dce9f451ea44c62dd --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd