implantacao.rst.in
7.95 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
Implantação
===========
Preparação da estação de trabalho
---------------------------------
Para gerenciar o SPB, é necessária uma estação de trabalho GNU/Linux,
que pode ser Debian 8 ou posterior, Ubuntu 14.04 ou superior, ou CentOS
7 ou superior (e equivalentes como RHEL 7 ou superior, ou Fedora). O
processo também pode ser feito em outros sistemas, desde que os pacotes
equivalentes estejam instalados.
As seguintes ferramentas serão necessárias:
* git_: ferramenta de controle de versão.
* chake_: ferramenta de gestão de configuração.
.. _chake: https://gitlab.com/terceiro/chake
.. _git: http://git-scm.com/
Para instalar em Debian/Ubuntu::
$ sudo apt-get install git ruby
$ sudo gem install chake
Para instalar em CentOS/RHEL/Fedora::
$ sudo yum install git ruby
$ sudo gem install chake
Além dessas ferramentas, será necessário um emulador de terminal. O
emulador de terminal padrão do seu ambiente de trabalho, ou qualquer
outro, vai servir.
Obtendo o repositório de configuração
-------------------------------------
Para iniciar, é necessário uma conta e usuário no SPB, com uma chave SSH
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
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
onde foi clonado o repositório::
$ cd softwarepublico/
Preparação dos servidores
-------------------------
* Os servidores precisam estar acessíveis por SSH. Caso necessário,
podem ser feitas configurações do SSH em
``config/@@SPB_ENV@@/ssh_config`` para isso.
* O usuário que vai conectar via SSH nos servidores precisa:
* ter acesso SSH configurado via chave SSH para evitar digitar senha.
* ter permissão de usar ``sudo`` sem a necessidade de digitar senha.
Configuração do ambiente alvo
-----------------------------
O SPB tem o conceito de "ambientes", que são diferentes instalações da
mesma plataforma. Todas as informações específicas sobre um determinado
ambiente estão centralizadas em arquivos dentro do diretório
``config/${ambiente}/``. Por exemplo, o ambiente "local", que se destina
ao uso para desenvolvimento local com máquinas virtuais, possui o
seguinte conteúdo::
$ find config/local/ | sort
config/local/config.yaml
config/local/ips.yaml
config/local/ssh_config
Estes arquivos possuem a seguinte finalidade:
* ``config.yaml``: Parâmetros gerais de configuração
* ``ips.yaml``: Tabela de IP's (na rede local) das máquinas que compõem
o ambiente.
* ``ssh_config``: Configuração necessária para o SSH. Pode ser um
arquivo caso não seja necessária nenhuma configuração especial para
acessar as máquinas (e.g. se você está na mesma rede local que elas.
Vamos agora verificar o conteúdo de cada arquivo no ambiente
**@@SPB_ENV@@**. Primeiro, ``config.yaml``:
.. code-block:: yaml
@@config(config.yaml)@@
Para nossa sorte, o significado de cada um dos campo acima deve ser
autoexplicativo.
O arquivo ``ips.yaml`` contém uma tabela com os endereços IP de cada
servidor da plataforma na rede local. Exemplo:
.. code-block:: yaml
@@config(ips.yaml)@@
Já o arquivo ``ssh_config`` contém opções padrão de configuração do
``ssh`` para conexão às máquinas::
@@config(ssh_config)@@
Configuração do DNS
-------------------
A tabela a seguir foi gerada dinamicamente a partir da configuração do
ambiente **@@SPB_ENV@@**. As seguintes entradas precisam ser configuradas no
DNS:
.. include:: dns.rst
Verificando o ambiente
----------------------
Para listar as máquinas do ambiente::
$ rake nodes SPB_ENV=@@SPB_ENV@@
O comando acima deve dar o seguinte resultado::
integration ssh
email ssh
social ssh
database ssh
reverseproxy ssh
Note que todas as vezes que formos chamar ``rake``, será preciso
informar sobre qual ambiente desejamos operar (``SPB_ENV=@@SPB_ENV@@``).
Caso você for operar sobre apenas um ambiente, ou caso você queira
evitar digitação, você pode criar um arquivo ``local.rake`` na raiz do
repositório com o seguinte conteúdo::
ENV['SPB_ENV'] ||= '@@SPB_ENV@@'
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``.
Para testar a conectividade às máquinas, podemos executar um comando
nelas::
$ rake nodes SPB_ENV=@@SPB_ENV@@
$ <PROMPT PARA VOCÊ DIGITAR>
No prompt, entre um comando simples como ``sudo date``. O resultado deve ser
parecido com o seguinte::
$ rake run
$ sudo date
integration: $ sudo date
integration: Qui Mai 14 18:59:19 BRT 2015
email: $ sudo date
email: Qui Mai 14 18:59:22 BRT 2015
social: $ sudo date
social: Qui Mai 14 18:59:24 BRT 2015
database: $ sudo date
database: Qui Mai 14 18:59:27 BRT 2015
reverseproxy: $ sudo date
reverseproxy: Qui Mai 14 18:59:28 BRT 2015
Se o resultado se parece com o exemplo acima, e você não precisou digitar a sua
senha nehuma vez, significa que 1) você conseguiu conectar em todas as máquinas
e 2) o sudo sem senha está configurado corretamente. Está tudo certo para
começar!
Nota sobre certificado SSL
--------------------------
O repositório de gestão de configuração **não** contém os par de chaves
do cerficado SSL para o domínio **@@external_hostname@@**. Antes de
realizar a implantação, você deve colocar o par de chaves nos seguintes
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
seja criptografada com GnuPG, o que é suportado pela ferramente de
implantação `chake`. Isso pode ser feito da seguinte maneira::
$ cd cookbooks/reverse_proxy/files/host-reverseproxy/
# criptografar:
$ gpg --encrypt --recipient XXXXXXXX --output @@external_hostname@@.key.gpg @@external_hostname@@.key
# conferir que o conteúdo descriptografado está OK:
$ gpg --decrypt @@external_hostname@@.key.gpg
# apagar o arquivo sem criptografia:
$ rm @@external_hostname@@.key
# retornar ao diretório de origem
$ cd -
`XXXXXXXX` deve ser substituído pelo ID da chave que está sendo usada
para criptografar.
Antes de fazer a implantação, o `chake` vai enviar a chave privada
descriptografada apenas à máquina que vai ser o frontend HTTPS. Caso sua
chave GnuPG necessite de uma senha para ser usada, ela será solicitada.
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::
$ 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**.
Depois de completo o procedimento acima, para aplicar as configurações a
todos os servidores basta executar::
$ rake converge SPB_ENV=@@SPB_ENV@@
O comando ``converge`` na verdade é o *default*, então o seguinte é
equivalente::
$ rake SPB_ENV=@@SPB_ENV@@
Se você tiver configurado o ambiente **@@SPB_ENV@@** no ``local.rake``
(ver instruções acima), então o comando seguinte, também equivalente, é
muito mais simples::
$ rake
Todas as possibilidades de comandos serão listados se você executar
``rake -T``. Consulte também a documentação do chake_.