Download as
Browse Code »

Commit b61cbb2ab8954131d15e33ea8cb758bdebaeac95

Authored by Athos
1 parent 499d507b
Exists in master and in 66 other branches 3.x, add_you_are_here_breadcrumbs_label, api_for_colab, backup_not_prod, button_suspension_points_remove, cdtc_configuration, create_institution_bootstrap_modal, design_validation, dev-lappis, dev_env_minimal, disable_email_dev, docs, fix_edit_institution, fix_edit_software_with_another_license, fix_list_style_inside_article, fix_members_pagination, fix_models_translations, fix_no_license, fix_software_api, fix_software_block_migration, fix_validations_and_tests, focus_search_field_theme, gov-user-refactoring, gov-user-refactoring-rails4, header_fix, institution_modal_on_rating, kalibro-conf-refactoring, kalibro-processor-package, lxc, mailinglist_page_title, margin_fix, mezuro_cookbook, organization_rating_style_changes, performance, prezento, r3, refactor_software_communities, refactor_software_for_sisp, register_page, release-process, release-process-v2, remove-unused-images, remove_backup_emails, remove_secondary_email_from_user, removing_super_archives_email, review_message, scope2method, signals_user_noosfero, sisp_colab_config, sisp_dev, sisp_dev_master, sisp_simple_version, software_as_organization, software_catalog_style_fix, software_catalog_style_fixes, spb_minimal_env, spec_refactor, stable-4.x, stable-devel, support_docs, syslog, temp_soft_comm_refactoring, thread_dropdown, thread_page, update_software_api, update_softwares_boxes

update documentation

Showing 3 changed files with 114 additions and 25 deletions   Show diff stats
docs/arquitetura.rst.in
  Diff comments   View file @b61cbb2
... ... @@ -9,17 +9,78 @@ a seguir.
9 9 Servidores e serviços
10 10 ---------------------
11 11  
12   -*Esta seção é um trabalho em andamento. Ela cobrirá:*
  12 +Um proxy reverso trata requisições http e as direciona para uma segunda
  13 +máquna, onde são distribuidas para os serviços solicitados. Todos os bancos
  14 +de dados relevantes estão concentrados em uma única máquina e todos os
  15 +emails disparados pelo sistema partem de um mesmo relay.
13 16  
14   -* descrever arquitetura
15   -* descrever papel de cada máquina
16   -* descrever conexões
  17 +O ambiente é composto por 5 máquinas com funções distintas:
  18 +
  19 +* integration
  20 + * Segundo proxy reverso
  21 + * Repositórios Git
  22 + * Listas de email
  23 +
  24 +* email
  25 + * relay de email
  26 +
  27 +* social
  28 + * Máquina dedicada para rede social Noosfero
  29 +
  30 +* database
  31 + * Servidor de banco de dados PostgreSQL
  32 +
  33 +* reverseproxy
  34 + * proxy reverso
  35 +
  36 +Apenas as máquinas reverseproxy e email possuem IP's externos. A primeira para
  37 +receber requisições HTTP/HTTPS (portas 80 e 443) e possibilitar que usuários
  38 +utilizem os repositórios git (porta 22) e a última para receber emails (porta
  39 +25). Além disso, todas as máquinas aceitam conexões ssh originadas apenas da
  40 +máquina integration, ou seja, não é possível, de acordo com as regras de
  41 +firewall, realizar conexões ssh nas demais máquinas se a conexão não for
  42 +originada da integration. Conexões na porta 22 da máquina reverseproxy são
  43 +redirecionadas para integration. As máquinas email, social e database aceitam
  44 +conexão SSH vindas da integration na porta 22 e a reverseproxy em uma porta
  45 +alternativa, especificada no arquivo de configuração do ambiente,
  46 +config/$SPB_ENV/config.yaml pelo valor passado a 'alt_ssh_port'.
  47 +
  48 +Por exemplo, para se conectar na máquina email é necessário estabelecer conexão
  49 +SSH na porta 22 da reverseproxy, esta conexão será redirecionada para a máquina
  50 +integration e finalmente, partindo desta, pode-se realizar a conexão com a
  51 +máquina email na porta 22. Ainda como exemplo, caso seja necessária uma conexão
  52 +na máquina reverseproxy, deve-se estabelecer conexão na porta 22 da mesma, esta
  53 +conexão será redirecionada para a máquina integration e finalmente, partindo
  54 +desta, pode-se realizar a conexão com a máquina reverse proxy na porta definida
  55 +por 'alt_ssh_port' definida em config/$SPB_ENV/config.yaml.
  56 +
  57 +Note que, como será demonstrado neste manual, existem atalhos definidos no
  58 +repositório de gestão de configuração para simplificar o acesso por SSH às
  59 +máquinas. Internamente, as máquinas integration e social também rodam web
  60 +servers para servirem suas aplicações. Por fim, as máquinas integration e social
  61 +conectam-se em database usando a porta 5432 para acesso aos bancos de dados.
17 62  
18 63 Gestão de configuração
19 64 ----------------------
20 65  
21   -*Esta seção é um trabalho em andamento. Ela cobrirá:*
  66 +O repositório de gestão de configuração se encontra em
  67 +git@portal.softwarepublico.gov.br:softwarepublico/softwarepublico.git e pode
  68 +ser obtido a partir do comando::
  69 +
  70 + $ git clone git@portal.softwarepublico.gov.br:softwarepublico/softwarepublico.git
  71 +
  72 +Note que para tal, é necessário possuir uma conta no Portal do SPB com chaves
  73 +SSH configuradas.
  74 +
  75 +Este repositório contém scripts que realizam todos os passos necessários
  76 +para a instalação, configuração e manutenção do ambiente. Isto é feito
  77 +através de scripts em linguagem Ruby que utilizam um programa chamado Chef,
  78 +para a automatização de configurações de ambientes. Mais informações em
  79 +https://docs.chef.io.
22 80  
23   -* adicionar links com o repositório de gestão de configuração
24   -* descrever repositório de gestão de configuração
25   -* descrever como o chake funciona
  81 +Os scripts mencionados são gerenciados por uma segunda ferramenta, Chake, que
  82 +elimina a necessidade de um servidor Chef dedicado para gerenciar as máquinas
  83 +do ambiente. O Chake conecta-se em cada uma das máquinas descritas via SSH,
  84 +copiando scripts e outros arquivos, contendo as diretrizes necessárias para
  85 +instalar e configurar todo o ambiente. Mais informações em
  86 +https://github.com/terceiro/chake.
... ...
docs/implantacao.rst.in
  Diff comments   View file @b61cbb2
... ... @@ -41,7 +41,7 @@ configurada.
41 41 Para obter o repositório de configuração, é necessário clonar o
42 42 repositório com ``git``::
43 43  
44   - $ git clone git@beta.softwarepublico.gov.br:softwarepublico/softwarepublico.git
  44 + $ git clone git@portal.softwarepublico.gov.br:softwarepublico/softwarepublico.git
45 45  
46 46 A partir daqui, todos os passos serão executados de dentro do
47 47 repositório, então se certifique que o seu *shell* está no diretório
... ... @@ -63,14 +63,7 @@ Preparação dos servidores
63 63  
64 64 * ter acesso SSH configurado via chave SSH para evitar digitar senha,
65 65 a partir da estação de trabalho utilizada. Ou seja, a chave pública
66   - SSH **da estação de trabalho** deve ser copiada para cada servidor,
67   - e.g.::
68   -
69   - $ ssh-copy-id reverseproxy
70   - $ ssh-copy-id integration
71   - $ ssh-copy-id social
72   - $ ssh-copy-id database
73   - $ ssh-copy-id email
  66 + SSH **da estação de trabalho** deve ser copiada para cada servidor.
74 67  
75 68 * O ``sudo`` não deve estar configurado com a opção ``requiretty``. Se
76 69 houver uma linha como a seguinte em ``/etc/sudoers``, ela deve ser
... ... @@ -161,10 +154,17 @@ repositório com o seguinte conteúdo::
161 154  
162 155 Isto fará com que o valor e ``SPB_ENV`` seja sempre ``@@SPB_ENV@@``, a
163 156 não ser que você informe na linha de comando. Daqui para frente, vamos
164   -sempre exibir o parâmetro ``SPB_ENV=@@SPB_ENV@@``, mas lembre-se que ele pode ser omitido se você tiver configurado o *default* em ``local.rake``.
  157 +sempre exibir o parâmetro ``SPB_ENV=@@SPB_ENV@@``, mas lembre-se que ele pode
  158 +ser omitido se você tiver configurado o *default* em ``local.rake``.
  159 +
  160 +Para testar a conectividade às máquinas, devemos antes realizar a
  161 +preconfiguração das máquinas, caso o sistema nunca tenha sido instalado.
  162 +Note que se este passo só deve ser realizado uma única vez::
165 163  
166   -Para testar a conectividade às máquinas, podemos executar um comando
167   -nelas::
  164 + $ rake preconfig SPB_ENV=@@SPB_ENV@@
  165 +
  166 +Finalmente, para testar a conectividade às máquinas, podemos executar um
  167 +comando nelas::
168 168  
169 169 $ rake run SPB_ENV=@@SPB_ENV@@
170 170 $ <PROMPT PARA VOCÊ DIGITAR>
... ... @@ -201,7 +201,7 @@ locais:
201 201 * `cookbooks/reverse_proxy/files/host-reverseproxy/@@external_hostname@@.crt`: certificado (chave pública), em formato PEM.
202 202 * `cookbooks/reverse_proxy/files/host-reverseproxy/@@external_hostname@@.key`: chave privada, em formato PEM.
203 203  
204   -Para uma melhor segurança da chave privada, e recomendado que a mesma
  204 +Para uma melhor segurança da chave privada, é recomendado que a mesma
205 205 seja criptografada com GnuPG, o que é suportado pela ferramente de
206 206 implantação `chake`. Isso pode ser feito da seguinte maneira::
207 207  
... ... @@ -227,11 +227,10 @@ Primeira instalação
227 227  
228 228 Uma vez configurados os parâmetros em ``config/@@SPB_ENV@@/``, podemos
229 229 dar início à instalação. O primeiro passo é uma preconfiguração que
230   -precisamos fazer::
  230 +precisamos fazer, caso não tenha sido feito em "Verificando o Ambiente"::
231 231  
232 232 $ rake preconfig SPB_ENV=@@SPB_ENV@@
233 233  
234   -
235 234 Este comando vai fazer uma configuração inicial que é necessária para o
236 235 resto do processo, e **só é necessária fazer uma vez**.
237 236  
... ...
docs/manutencao.rst.in
  Diff comments   View file @b61cbb2
... ... @@ -4,9 +4,38 @@ Manutenção
4 4 Mantendo o sistema atualizado
5 5 -----------------------------
6 6  
7   -*Esta seção é um trabalho em andamento.*
  7 +É importante que não apenas os software relacionados ao Portal do SPB sejam
  8 +mantidos atualizados, mas também outros pacotes do sistema provenientes dos
  9 +repositórios oficiais da distribuição utilizada. Tais atualizações são
  10 +tratadas pelos scripts de gestão de configuração do ambiente, de modo que
  11 +para que se mantenha todo o sistema atualizado, basta seguir os passos de
  12 +atualização do Portal do SPB na seção de Implantação, ou seja::
  13 +
  14 + $ git pull
  15 + $ rake converge SPB_ENV=@@SPB_ENV@@
8 16  
9 17 Modificando configurações
10 18 -------------------------
11 19  
12   -*Esta seção é um trabalho em andamento.*
  20 +Como descrito na seção de Implantação, as configurações específicas de
  21 +um determinado ambiente se encontram centralizadas nos arquivos presentes em
  22 +``config/${ambiente}/``, de modo que em caso de necessidade de alterações nas
  23 +configurações, deve-se recorrer a tais arquivos.
  24 +
  25 +* ``config.yaml``
  26 + * Administradores do sistema
  27 + * Nome dos domínios (Portal, relay e mailman)
  28 + * IP's externos para reverseproxy e relay
  29 + * Porta de SSH para conexão interna à reverseproxy
  30 + * Outras configurações relevantes para o sistema
  31 +
  32 +* ``ips.yaml``
  33 + * IP's (rede local) das máquinas descritas na seção de Arquitetura
  34 +
  35 +* ``ssh_config``
  36 + * Arquivo de configuração para conexões SSH.
  37 +
  38 +Ao se modificarem configurações do ambiente que sejam permanentes, é
  39 +interessante que as mesmas sejam refletidas também nos repositórios de
  40 +gestão de configuração, para tal, contate os mantenedores do portal em
  41 +spb-dev@listas.softwarepublico.gov.br.
... ...