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. 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 ---------------------- 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, 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@@ $ 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 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 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.