Commit d850d96554a273d21f077c3e796230bab7fa4012
Exists in
master
and in
64 other branches
Merge branch 'update_doc' into 'master'
Update doc Still some fixes left. But I think we could send this one out after reviews... Next step would be to detail some steps like generating ad uploading ssh keys See merge request !34
Showing
3 changed files
with
114 additions
and
25 deletions
Show diff stats
docs/arquitetura.rst.in
| @@ -9,17 +9,78 @@ a seguir. | @@ -9,17 +9,78 @@ a seguir. | ||
| 9 | Servidores e serviços | 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 | |||
| 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 | Gestão de configuração | 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
| @@ -41,7 +41,7 @@ configurada. | @@ -41,7 +41,7 @@ configurada. | ||
| 41 | Para obter o repositório de configuração, é necessário clonar o | 41 | Para obter o repositório de configuração, é necessário clonar o |
| 42 | repositório com ``git``:: | 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 | A partir daqui, todos os passos serão executados de dentro do | 46 | A partir daqui, todos os passos serão executados de dentro do |
| 47 | repositório, então se certifique que o seu *shell* está no diretório | 47 | repositório, então se certifique que o seu *shell* está no diretório |
| @@ -63,14 +63,7 @@ Preparação dos servidores | @@ -63,14 +63,7 @@ Preparação dos servidores | ||
| 63 | 63 | ||
| 64 | * ter acesso SSH configurado via chave SSH para evitar digitar senha, | 64 | * ter acesso SSH configurado via chave SSH para evitar digitar senha, |
| 65 | a partir da estação de trabalho utilizada. Ou seja, a chave pública | 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 | * O ``sudo`` não deve estar configurado com a opção ``requiretty``. Se | 68 | * O ``sudo`` não deve estar configurado com a opção ``requiretty``. Se |
| 76 | houver uma linha como a seguinte em ``/etc/sudoers``, ela deve ser | 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,10 +154,17 @@ repositório com o seguinte conteúdo:: | ||
| 161 | 154 | ||
| 162 | Isto fará com que o valor e ``SPB_ENV`` seja sempre ``@@SPB_ENV@@``, a | 155 | Isto fará com que o valor e ``SPB_ENV`` seja sempre ``@@SPB_ENV@@``, a |
| 163 | não ser que você informe na linha de comando. Daqui para frente, vamos | 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 | $ rake run SPB_ENV=@@SPB_ENV@@ | 169 | $ rake run SPB_ENV=@@SPB_ENV@@ |
| 170 | $ <PROMPT PARA VOCÊ DIGITAR> | 170 | $ <PROMPT PARA VOCÊ DIGITAR> |
| @@ -201,7 +201,7 @@ locais: | @@ -201,7 +201,7 @@ locais: | ||
| 201 | * `cookbooks/reverse_proxy/files/host-reverseproxy/@@external_hostname@@.crt`: certificado (chave pública), em formato PEM. | 201 | * `cookbooks/reverse_proxy/files/host-reverseproxy/@@external_hostname@@.crt`: certificado (chave pública), em formato PEM. |
| 202 | * `cookbooks/reverse_proxy/files/host-reverseproxy/@@external_hostname@@.key`: chave privada, em formato PEM. | 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 | seja criptografada com GnuPG, o que é suportado pela ferramente de | 205 | seja criptografada com GnuPG, o que é suportado pela ferramente de |
| 206 | implantação `chake`. Isso pode ser feito da seguinte maneira:: | 206 | implantação `chake`. Isso pode ser feito da seguinte maneira:: |
| 207 | 207 | ||
| @@ -227,11 +227,10 @@ Primeira instalação | @@ -227,11 +227,10 @@ Primeira instalação | ||
| 227 | 227 | ||
| 228 | Uma vez configurados os parâmetros em ``config/@@SPB_ENV@@/``, podemos | 228 | Uma vez configurados os parâmetros em ``config/@@SPB_ENV@@/``, podemos |
| 229 | dar início à instalação. O primeiro passo é uma preconfiguração que | 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 | $ rake preconfig SPB_ENV=@@SPB_ENV@@ | 232 | $ rake preconfig SPB_ENV=@@SPB_ENV@@ |
| 233 | 233 | ||
| 234 | - | ||
| 235 | Este comando vai fazer uma configuração inicial que é necessária para o | 234 | Este comando vai fazer uma configuração inicial que é necessária para o |
| 236 | resto do processo, e **só é necessária fazer uma vez**. | 235 | resto do processo, e **só é necessária fazer uma vez**. |
| 237 | 236 |
docs/manutencao.rst.in
| @@ -4,9 +4,38 @@ Manutenção | @@ -4,9 +4,38 @@ Manutenção | ||
| 4 | Mantendo o sistema atualizado | 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 | Modificando configurações | 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. |