diff --git a/docs/arquitetura.rst.in b/docs/arquitetura.rst.in index 7316e5d..16eeb77 100644 --- a/docs/arquitetura.rst.in +++ b/docs/arquitetura.rst.in @@ -9,17 +9,78 @@ a seguir. Servidores e serviços --------------------- -*Esta seção é um trabalho em andamento. Ela cobrirá:* +Um proxy reverso trata requisições http e as direciona para uma segunda +máquna, onde são distribuidas para os serviços solicitados. Todos os bancos +de dados relevantes estão concentrados em uma única máquina e todos os +emails disparados pelo sistema partem de um mesmo relay. -* descrever arquitetura -* descrever papel de cada máquina -* descrever conexões +O ambiente é composto por 5 máquinas com funções distintas: + +* integration + * Segundo proxy reverso + * Repositórios Git + * Listas de email + +* email + * relay de email + +* social + * Máquina dedicada para rede social Noosfero + +* database + * Servidor de banco de dados PostgreSQL + +* reverseproxy + * proxy reverso + +Apenas as máquinas reverseproxy e email possuem IP's externos. A primeira para +receber requisições HTTP/HTTPS (portas 80 e 443) e possibilitar que usuários +utilizem os repositórios git (porta 22) e a última para receber emails (porta +25). Além disso, todas as máquinas aceitam conexões ssh originadas apenas da +máquina integration, ou seja, não é possível, de acordo com as regras de +firewall, realizar conexões ssh nas demais máquinas se a conexão não for +originada da integration. Conexões na porta 22 da máquina reverseproxy são +redirecionadas para integration. As máquinas email, social e database aceitam +conexão SSH vindas da integration na porta 22 e a reverseproxy em uma porta +alternativa, especificada no arquivo de configuração do ambiente, +config/$SPB_ENV/config.yaml pelo valor passado a 'alt_ssh_port'. + +Por exemplo, para se conectar na máquina email é necessário estabelecer conexão +SSH na porta 22 da reverseproxy, esta conexão será redirecionada para a máquina +integration e finalmente, partindo desta, pode-se realizar a conexão com a +máquina email na porta 22. Ainda como exemplo, caso seja necessária uma conexão +na máquina reverseproxy, deve-se estabelecer conexão na porta 22 da mesma, esta +conexão será redirecionada para a máquina integration e finalmente, partindo +desta, pode-se realizar a conexão com a máquina reverse proxy na porta definida +por 'alt_ssh_port' definida em config/$SPB_ENV/config.yaml. + +Note que, como será demonstrado neste manual, existem atalhos definidos no +repositório de gestão de configuração para simplificar o acesso por SSH às +máquinas. Internamente, as máquinas integration e social também rodam web +servers para servirem suas aplicações. Por fim, as máquinas integration e social +conectam-se em database usando a porta 5432 para acesso aos bancos de dados. Gestão de configuração ---------------------- -*Esta seção é um trabalho em andamento. Ela cobrirá:* +O repositório de gestão de configuração se encontra em +git@portal.softwarepublico.gov.br:softwarepublico/softwarepublico.git e pode +ser obtido a partir do comando:: + + $ git clone git@portal.softwarepublico.gov.br:softwarepublico/softwarepublico.git + +Note que para tal, é necessário possuir uma conta no Portal do SPB com chaves +SSH configuradas. + +Este repositório contém scripts que realizam todos os passos necessários +para a instalação, configuração e manutenção do ambiente. Isto é feito +através de scripts em linguagem Ruby que utilizam um programa chamado Chef, +para a automatização de configurações de ambientes. Mais informações em +https://docs.chef.io. -* adicionar links com o repositório de gestão de configuração -* descrever repositório de gestão de configuração -* descrever como o chake funciona +Os scripts mencionados são gerenciados por uma segunda ferramenta, Chake, que +elimina a necessidade de um servidor Chef dedicado para gerenciar as máquinas +do ambiente. O Chake conecta-se em cada uma das máquinas descritas via SSH, +copiando scripts e outros arquivos, contendo as diretrizes necessárias para +instalar e configurar todo o ambiente. Mais informações em +https://github.com/terceiro/chake. diff --git a/docs/implantacao.rst.in b/docs/implantacao.rst.in index 8e6e935..946bef1 100644 --- a/docs/implantacao.rst.in +++ b/docs/implantacao.rst.in @@ -41,7 +41,7 @@ configurada. Para obter o repositório de configuração, é necessário clonar o repositório com ``git``:: - $ git clone git@beta.softwarepublico.gov.br:softwarepublico/softwarepublico.git + $ git clone git@portal.softwarepublico.gov.br:softwarepublico/softwarepublico.git A partir daqui, todos os passos serão executados de dentro do repositório, então se certifique que o seu *shell* está no diretório @@ -63,14 +63,7 @@ Preparação dos servidores * ter acesso SSH configurado via chave SSH para evitar digitar senha, a partir da estação de trabalho utilizada. Ou seja, a chave pública - SSH **da estação de trabalho** deve ser copiada para cada servidor, - e.g.:: - - $ ssh-copy-id reverseproxy - $ ssh-copy-id integration - $ ssh-copy-id social - $ ssh-copy-id database - $ ssh-copy-id email + SSH **da estação de trabalho** deve ser copiada para cada servidor. * O ``sudo`` não deve estar configurado com a opção ``requiretty``. Se houver uma linha como a seguinte em ``/etc/sudoers``, ela deve ser @@ -161,10 +154,17 @@ repositório com o seguinte conteúdo:: Isto fará com que o valor e ``SPB_ENV`` seja sempre ``@@SPB_ENV@@``, a não ser que você informe na linha de comando. Daqui para frente, vamos -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``. +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``. + +Para testar a conectividade às máquinas, devemos antes realizar a +preconfiguração das máquinas, caso o sistema nunca tenha sido instalado. +Note que se este passo só deve ser realizado uma única vez:: -Para testar a conectividade às máquinas, podemos executar um comando -nelas:: + $ rake preconfig SPB_ENV=@@SPB_ENV@@ + +Finalmente, para testar a conectividade às máquinas, podemos executar um +comando nelas:: $ rake run SPB_ENV=@@SPB_ENV@@ $ @@ -201,7 +201,7 @@ locais: * `cookbooks/reverse_proxy/files/host-reverseproxy/@@external_hostname@@.crt`: certificado (chave pública), em formato PEM. * `cookbooks/reverse_proxy/files/host-reverseproxy/@@external_hostname@@.key`: chave privada, em formato PEM. -Para uma melhor segurança da chave privada, e recomendado que a mesma +Para uma melhor segurança da chave privada, é recomendado que a mesma seja criptografada com GnuPG, o que é suportado pela ferramente de implantação `chake`. Isso pode ser feito da seguinte maneira:: @@ -227,11 +227,10 @@ Primeira instalação Uma vez configurados os parâmetros em ``config/@@SPB_ENV@@/``, podemos dar início à instalação. O primeiro passo é uma preconfiguração que -precisamos fazer:: +precisamos fazer, caso não tenha sido feito em "Verificando o Ambiente":: $ rake preconfig SPB_ENV=@@SPB_ENV@@ - Este comando vai fazer uma configuração inicial que é necessária para o resto do processo, e **só é necessária fazer uma vez**. diff --git a/docs/manutencao.rst.in b/docs/manutencao.rst.in index f5bf380..3a74b2b 100644 --- a/docs/manutencao.rst.in +++ b/docs/manutencao.rst.in @@ -4,9 +4,38 @@ Manutenção Mantendo o sistema atualizado ----------------------------- -*Esta seção é um trabalho em andamento.* +É importante que não apenas os software relacionados ao Portal do SPB sejam +mantidos atualizados, mas também outros pacotes do sistema provenientes dos +repositórios oficiais da distribuição utilizada. Tais atualizações são +tratadas pelos scripts de gestão de configuração do ambiente, de modo que +para que se mantenha todo o sistema atualizado, basta seguir os passos de +atualização do Portal do SPB na seção de Implantação, ou seja:: + + $ git pull + $ rake converge SPB_ENV=@@SPB_ENV@@ Modificando configurações ------------------------- -*Esta seção é um trabalho em andamento.* +Como descrito na seção de Implantação, as configurações específicas de +um determinado ambiente se encontram centralizadas nos arquivos presentes em +``config/${ambiente}/``, de modo que em caso de necessidade de alterações nas +configurações, deve-se recorrer a tais arquivos. + +* ``config.yaml`` + * Administradores do sistema + * Nome dos domínios (Portal, relay e mailman) + * IP's externos para reverseproxy e relay + * Porta de SSH para conexão interna à reverseproxy + * Outras configurações relevantes para o sistema + +* ``ips.yaml`` + * IP's (rede local) das máquinas descritas na seção de Arquitetura + +* ``ssh_config`` + * Arquivo de configuração para conexões SSH. + +Ao se modificarem configurações do ambiente que sejam permanentes, é +interessante que as mesmas sejam refletidas também nos repositórios de +gestão de configuração, para tal, contate os mantenedores do portal em +spb-dev@listas.softwarepublico.gov.br. -- libgit2 0.21.2