Software Público Brasileiro

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. Version 0.13 ou maior.
* python-sphinx_: ferramenta para gerar documentação HTML.

.. _chake: https://gitlab.com/terceiro/chake
.. _git: http://git-scm.com/
.. _python-sphinx: http://www.sphinx-doc.org/en/stable/

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. Mais informações em :doc:`/apoio`.

Para obter o repositório de configuração, é necessário clonar o
repositório com ``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
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 permissão de usar ``sudo`` sem a necessidade de digitar senha.

  * 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.
    Para mais informações, veja a :doc:`/apoio`.

* 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
  removida (ou comentada, como preferir)::

    $ Defaults requiretty

* A máquina ``integration`` precisa ter o utilitário ``netcat``. No
  CentOS 7, pode ser instalado o pacote ``nmap-ncat``.

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

.. _verificandoambiente:

Verificando o ambiente
----------------------

**Importante:** A máquina *integration* tem o requisito mínimo de 8Gb de
memória RAM.

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
    mezuro                                   ssh
    monitor                                  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, devemos antes realizar a
preconfiguração das máquinas, caso o sistema nunca tenha sido instalado.
Note que se este passo deve ser realizado uma **única vez**::

    $ 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>

No prompt, entre um comando simples como ``sudo date``. O resultado deve ser
parecido com o seguinte::

    $ rake run SPB_ENV=@@SPB_ENV@@
    $ 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
          mezuro: $ sudo date
          mezuro: Qui Mai 14 18:59:24 BRT 2015
         monitor: $ sudo date
         monitor: Qui Mai 14 18:59:25 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.
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, é 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, caso não tenha sido feito em :ref:`verificandoambiente`::

    $ 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_.


Atualizações
------------

O primeiro passo para realizar a atualização do ambiente consiste em entrar
na pasta do repositório de configuração. Em caso de dúvida, veja a seção
"Obtendo o Repositório de Configuração".

Em seguida atualize o repositório de gestão de configuração com o comando
abaixo::

    $ cd /diretorio/deconfiguracao/softwarepublico
    $ git pull

Após isso, basta executar o comando ``converge`` novamente no ambiente
especifico::

    $ rake converge SPB_ENV=[Ambiente Especifico]

Repare que ``SPB_ENV``, assume os seguintes valores de acordo com o ambiente
que será atualizado. Logo, se você deseja atualizar o ambiente de homologação
use ``SPB_ENV=homologa``. Se você deseja atualizar o ambiente de produção, use
``SPB_ENV=prod``.

Caso após a atualização o noosfero não funcionar corretamente, provavelmente
um erro de *'502 Bad Gateway'* irá aparecer, reinicie o ambiente social::

    $ rake run:social SPB_ENV=@@SPB_ENV@@
    $ sudo shutdown -r

Aguarde o ambiente reiniciar, e atualize a pagina.

Atualizações pontuais
---------------------

Algumas vezes é preciso fazer atualizações em apenas um dos ambientes, como
por exemplo, aplicar uma correção de bug. Tais correções/atualizações podem
não precisar convergir o ambiente inteiro. Neste caso é possível fazer a
atualização em ambientes especificos, por meio dos comandos abaixo:

  * Atualizar a social: rake converge:social SPB_ENV=homologa
  * Atualizar a integration:  rake converge:social SPB_ENV=homologa
  * Atualizar a email: rake converge:email SPB_ENV=homologa
  * Atualizar a database: rake converge:database SPB_ENV=homolga
  * Atualizar a mezuro: rake converge:mezuro SPB_ENV=homolga
  * Atualizar a monitor: rake converge:monitor SPB_ENV=homolga
  * Atualizar a reverseproxy: rake converge:reverseproxy SPB_ENV=homologa

> Atenção: Estes comandos devem ser executados dentro da pasta
"softwarepublico", previamente clonada do repositório. Em caso de dúvida
consulte a seção "Obtendo o Repositório de Configuração".

Lembrando que a variável SPB_ENV, assume o valor do ambiente em que será
executado a atulização. Logo, se você estiver querendo atualizar o ambiente
de homologação então use SPB_ENV=homologa, caso você deseje atualizar o
ambiente de produção utilize SPB_ENV=prod.