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

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
Antonio Terceiro
2 parents d82fc49f b61cbb2a
Showing 3 changed files with 114 additions and 25 deletions Show diff stats
docs/arquitetura.rst.in
docs/implantacao.rst.in
docs/manutencao.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.
@@ -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@@
     $ <PROMPT PARA VOCÊ DIGITAR>
@@ -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**.
  
@@ -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.
...	...	@@ -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.
...	...
...	...	@@ -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
...	...
...	...	@@ -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.
...	...