Estrutura básica do Manual de Operação

Antonio Terceiro · Sergio Oliveira
1 parent 5f9c8637
Showing 11 changed files with 71 additions and 530 deletions Show diff stats
docs/arquitetura.rst
docs/backup.rst
docs/conf.py
docs/dependencies.rst
docs/firewall.rst
docs/implantacao.rst
docs/index.rst
docs/install.rst
docs/manutencao.rst
tasks/doc.rake
test/dns_test.sh
@@ -0,0 +1,2 @@
+Arquitetura
+===========
@@ -0,0 +1,4 @@
+Backup
+======
+
+
@@ -44,7 +44,7 @@ master_doc = &#39;index&#39;
 # General information about the project.
 project = u'softwarepublico'
-copyright = u'2014, Universidade de Brasília - UnB. Documentação licenciada sob a Licença Creative Commons Atribuição-CompartilhaIgual 4.0 Internacional'
+copyright = u'2014-2015, Universidade de Brasília - UnB. Documentação licenciada sob a Licença Creative Commons Atribuição-CompartilhaIgual 4.0 Internacional'
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -57,7 +57,7 @@ release = &#39;2.0&#39;
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
-#language = None
+language = 'pt_BR'
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -197,7 +197,7 @@ latex_elements = {
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
   ('index', 'softwarepublico.tex',
-   u'Documentação - Software Público Brasileiro (SPB)',
+   u'Software Público Brasileiro: Manual de Operação',
    u'Universidade de Brasília', 'manual'),
 ]
@@ -1,96 +0,0 @@
-
-.. _dependencies:
-
-Dependências
-============
-
-O repositório do SPB contém os pacotes que não são nativos do Sistema
-Operacional onde o mesmo o sistema do Portal do Software Público deve ser
-instalado. Esse repositório contém os pacotes referentes ao Bottle, Mailman-api,
-Solr, Colab e às dependências do Colab (pacote Colab-deps).
-
-Colab
-----------
-Esse pacote, contém o sistema Colab. O processo de
-criação desse pacote depende do pacote `python-virtualenv`, além de um
-conjunto de dependências python, contidos no pacote `colab-deps`, descrito na
-próxima seção. O processo de instalação desse pacote requer uma instalação
-prévia do pacote `colab-deps`, que é instalado automaticamente se o repositório
-do mesmo estiver disponível no conjunto de repositórios do `yum`.
-
-Colab-deps
-----------
-Este pacote contém as dependências *python* do Colab. Tais dependências foram
-encapsuladas em um ambiente virtual python (`python-virtualenv`), permitindo uma
-maior independência e, consequentemente, compatibilidade com o Sistema
-Operacional no qual o pacote seja instalado. Esse pacote é composto pelas
-ferramentas listadas a seguir.
-
-* Chardet
-* Django
-* Django-browserid
-* Django-cliauth
-* Django-common
-* Django-conversejs
-* Django-haystack
-* Django-hitcounter
-* Django-i18n-model
-* Django-mobile
-* Django-mptt
-* Django-piston
-* Django-revproxy
-* Django-taggit
-* Django-tastypie
-* Dpaste
-* Etiquetando
-* Eventlet
-* Fancy_tag
-* Feedzilla
-* Grab
-* Gunicorn
-* Html2text
-* Lorem-ipsum-generator
-* Lxml
-* Paste
-* Pip
-* Poster
-* Psycopg2
-* Pure-sasl
-* Pygments
-* Pysolr
-* Python-dateutil
-* Python-memcached
-* Python-mimeparse
-* PyYAML
-* Raven
-* Repoze.lru
-* Requests
-* Setuptools
-* Six
-* Sleekxmpp
-* South
-* Stemming
-* Tornado
-* Transliterate
-
-
-Mailman-api
------------
-
-Esse pacote contém o Mailman-api. Esta ferramenta python possui como
-dependência os pacotes Bottle e python. Como o Bottle não é provido
-nativamente pelo CentOS 7, foi necessário empacotá-lo separadamente.
-
-Bottle
------------
-
-Esse pacote contém a ferramenta Bottle, um framowork web escrito em
-python, e requisito para a utilização da ferramenta Mailman-api. Este pacote
-possui como dependência o pacote python, que está disponível nativamente no
-CentOS.
-
-Solr
-----
-Esse pacote contém a ferramenta python Bottle, e integra o conjunto de
-ferramentas do SPB. Sua instalação requer o pacote Java, que já existe
-nativamente no CentOS.
@@ -0,0 +1,2 @@
+Gestão do firewall
+==================
@@ -0,0 +1,4 @@
+Implantação
+===========
+
+.. include:: dns.rst
-
-Documentação do Software Público Brasileiro (SPB)
-=================================================
+Software Público Brasileiro: Manual de Operação
+***********************************************
 Introdução
-----------
+==========
 Bem-vindo a documentação do Portal do Software Público Brasileiro.
-O Portal do Software Público Brasileiro (SPB), na prática, é um sistema Web
-que se consolidou como um ambiente de compartilhamento de softwares. O projeto
-de evolução deste portal está sendo desenvolvido pela Universidade de Brasília.
+O Portal do Software Público Brasileiro (SPB) é uma plataforma de
+compartilhamento e colaboração no desenvolvimento de softwares. O
+projeto de evolução deste portal está sendo desenvolvido pela
+Universidade de Brasília.
-Hoje o SPB é um sistema Web composto por ferramentas livres integradas porém com
-desenvolvimento e comunidades independentes.
+O SPB é composto de um conjunto de ferramentas com funcionalidades
+complementares, que são desenvolvidas de forma independentes pelas suas
+respectivas comunidades. Estas ferramentas estão sendo integradas pela
+nossa equipe de forma a apresentar uma experiência de usuário
+consistente.
-As ferramentas que compõe o Software Público são:
+* O Colab_ é uma ferramenta especializada na integração de outras
+  ferramentas. O Colab fornece um ponto central de autenticação de
+  usuários para as demais ferramentas da plataforma, indexa informações
+  das demais ferramentas para busca e gamificação, e fornece integração
+  visual entre as diferentes ferramentas que compõem o SOB. O Colab é um
+  software livre criado no Brasil, que teve sua origem no
+  Programa `Interlegis` do Senado Federal.
-* **Mailman**: Para lista de e-mail estamos utilizando o Mailman na versão 2, que é um software gratuito para gerenciamento de discussão eletrônica de e-mail e listas *e-newsletter*;
+.. _Colab: https://github.com/colab-community
+.. _`Programa Interlegis do Senado Federal`: http://www.interlegis.leg.br/
-* **Noosfero**: Para rede social estamos utilizando o Noosfero que é uma plataforma web livre para criação de redes sociais com blog, e-Portifólios, CMS, RSS, discussão temática, agenda de eventos, galeria de imagens, chat, entre outros. Ele foi desenvolvido pela Cooperativa de Tecnologias Livres – Colivre 3 em 2007, sob a licença AGPL v.3, com a proposta de permitir ao usuário criar sua própria rede social personalizada, livre e autônoma;
+* O Noosfero_ é uma plataforma para criação de redes sociais que conta com
+  diversas funcionalidades de gestão de conteúdo como blogs, galeria de
+  imagens e vídeos, entre outros. O Noosfero também é um software livre
+  criado no Brasil, iniciado em 2007 pela COLIVRE_ e que hoje conta com
+  uma comunidade de desenvolvimento que inclui o SERPRO, a Universidade de
+  Brasília e o Fórum Brasileiro de Economia Solidária.
-* **Gitlab**: Para Forge para Git estamos utilizando o GitLab, que é um software livre de colaboração de código *online* que utiliza a ferramenta de gerência de código fonte Git;
+.. _Noosfero: http://www.noosfero.org/
+.. _COLIVRE: http://www.colivre.coop.br/
-* **Solr**: Para Plataforma de Buscas estamos utilizando Apache Solr, que é uma plataforma de busca open source da Apache Lucene escrita em Java;
+* O Gitlab_ é uma plataforma para desenvolvimento colaborativo. Projetos
+  no gitlab são mantidos em repositorios ``git``, com gestão de tarefas
+  (*issue tracker*), *merge requests*, gestão de marcos (*milestones*),
+  suporte a integração com plataformas de integração contínua e
+  notificações.
-* **Persona**: Para suporte a autentição Federada estamos utilizando o Mozilla Persona, que foi desenvolvido pela Mozilla Foundation.
+.. _Gitlab: https://www.gitlab.com/
-* **Colab**: Para integrar todas estas ferramentas estamos utilizando o Colab, que é uma plataforma de integração de ferramentas. Nele, são também integradas as interfaces das ferramentas para que, ao navegar, o usuário tenha a sensação de estar navegando em uma única ferramenta.
+* O `GNU Mailman`_ é uma gerenciador de listas de email tradicionalmente
+  usado por diversas organizações no Brasil e no mundo.
+.. _`GNU Mailman`: http://www.gnu.org/software/mailman/
-Conteúdos
-----------
+O restando deste manual descreve a arquitetura do SPB bem como os
+procedimentos necessários para sua implantação, manutenção, backup e
+restauração e gestão de firewall.
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 1
+
-   install
-   dependencies
-   dns
+.. include:: arquitetura.rst
+.. include:: implantacao.rst
+.. include:: manutencao.rst
+.. include:: backup.rst
+.. include:: firewall.rst
@@ -1,403 +0,0 @@
-Instalação
-==========
-
-.. Descrição dos pacotes e listagem das dependências de cada pacote
-
-Para instalação das ferramentas que compõem o Software Público, é necessária a
-instalação de um conjunto de pacotes RPM. Um pacote RPM consiste em uma coleção
-de uma ou mais ferramentas que permite um meio automático de instalação,
-atualização, configuração e remoção de softwares. 
-
-O processo de instalação aqui descrito permite a instalação e configuração
-desses pacotes em uma máquina com o Sistema Operacional CentOS 7 instalado e
-atualizado. Os pacotes a seguir já são fornecidos nativamente pelo Sistema
-Operacional, não sendo necessária uma configuração adicional para a
-instalação dos mesmos.
-
-* Mailman
-* Nginx
-* PostgreSQL Server
-
-Somados a esses, alguns pacotes não fornecidos nativamente também são
-necessários. Os mesmos estão listados a seguir.
-
-* Noosfero
-* Gitlab
-* Gitlab-deps
-* Solr
-* Colab
-* Colab-deps
-* Mailman-api
-
-Para disponibilizar cada pacote não nativo do CentOS 7, fez-se um levantamento
-das dependências de cada ferramenta empacotada, bem como do processo de 
-instalação de cada uma, de modo a automatizar esse processo.
-A seção :ref:`dependencies` descreve brevemente o levantamento de dependências
-feito.
-
-
-Repositório do SPB
--------------------
-
-.. Configuração do repositório yum em /etc/yum.repos.d
-
-Para instalação dos pacotes existentes no repositório do SPB através do
-gerenciador de instalação e remoção de pacotes do CentOS (o *Yum*), é preciso
-adicionar o arquivo de configuração desse repositório no diretório
-`/etc/yum.repos.d/` do Sistema Operacional onde o Portal do Software Público deve
-Procedimento:
-
-Os comandos a seguir devem ser executados via terminal, com permissões de super
-usuário do sistema.
-
-1. Instalar (caso não esteja instalado) o programa `wget`, para download das
-   configurações de repositório
-
-::
-
-   yum install -y wget
-
-2. Ir para o diretório `/etc/yum.repos.d/`
-
-::
-
-   cd /etc/yum.repos.d/
-
-3. Fazer o *download* dos arquivos de configuração nesse diretório:
-
-::
-
-   wget http://download.opensuse.org/repositories/isv:/spb:/colab/CentOS_7/isv:spb:colab.repo
-   wget http://download.opensuse.org/repositories/isv:/spb:/mailman-api/CentOS_7/isv:spb:mailman-api.repo
-   wget http://download.opensuse.org/repositories/isv:/spb:/gitlab/CentOS_7/isv:spb:gitlab.repo
-
-4. Instalar repositório para instalação do servidor web Nginx:
-
-::
-
-   rpm -i http://nginx.org/packages/centos/7/noarch/RPMS/nginx-release-centos-7-0.el7.ngx.noarch.rpm
-
-
-Instalação das Ferramentas (via pacote)
----------------------------------------
-
-.. Instalação dos pacotes via yum
-
-Após a configuração do repositório do SPB, todos os pacotes deverão estar
-disponíveis através do *yum*. Ainda que algumas dependências sejam tratadas
-automaticamente, o comportamento de alguns pacotes é dependente da ordem em que
-os mesmos são instalados. Portanto, deve-se executar a instalação na ordem
-especificada a seguir.
-Os comandos a seguir devem ser executados via terminal, com permissões de super
-usuário do sistema.
-
-Procedimento:
-
-1. Instalar o pacote PostreSQL Server
-
-::
-
-   yum install -y postgresql-server
-
-2. Instalar o pacote do servidor de estrutura de dados Redis
-
-::
-
-   yum install -y redis
-
-3. Instalar os pacotes do source forge Gitlab e gerenciador de repositórios
-   Gitlab-shell
-
-::
-
-   yum install -y gitlab gitlab-shell
-
-4. Instalar o pacote da ferramenta Noosfero
-
-::
-
-   yum install -y noosfero
-
-5. Instalar o pacote da ferramenta de integração Colab
-
-::
-
-   yum install -y colab
-
-6. Instalar o pacote do servidor web Nginx
-
-::
-
-   yum install -y nginx
-
-Configurações
---------------
-
-
-Nginx
-+++++
-
-Para configurar o Nginx crie o arquivo ``/etc/nginx/conf.d/colab.conf`` com o conteúdo abaixo: 
-
-.. code-block:: nginx
-
-   upstream colab {
-     server                127.0.0.1:8001  fail_timeout=10s;
-   }
-
-   server {
-     listen                *:80;
-
-     server_name           beta.softwarepublico.gov.br;
-     return                301 https://$server_name$request_uri;
-   }
-
-   server {
-     listen                *:443 ssl;
-
-     server_name           beta.softwarepublico.gov.br;
-
-     ssl on;
-
-     ssl_certificate           /etc/nginx/colab.crt;
-     ssl_certificate_key       /etc/nginx/colab.key;
-     ssl_session_cache         shared:SSL:10m;
-     ssl_session_timeout       5m;
-     ssl_protocols             SSLv3 TLSv1 TLSv1.1 TLSv1.2;
-     ssl_ciphers               HIGH:!aNULL:!MD5;
-     ssl_prefer_server_ciphers on;
-
-     access_log            /var/log/nginx/ssl-colab.access.log;
-     error_log             /var/log/nginx/ssl-colab.error.log;
-
-     location /gitlab/assets/ {
-       alias  /var/lib/gitlab-assets/;
-     }
-
-     location / {
-       root  /usr/share/nginx/colab;
-       try_files $uri @colab-app;
-     }
-
-     location @colab-app {
-       proxy_pass              http://colab;
-       proxy_read_timeout      90;
-       proxy_connect_timeout   90;
-       proxy_redirect          off;
-       proxy_set_header        Host $host;
-       proxy_set_header        X-Real-IP $remote_addr;
-       proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
-       proxy_set_header        X-Forwarded-Proto https;
-     }
-   }
-
-
-Substitua o domínio de exemplo ``beta.softwarepublico.gov.br`` pelo domínio
-desejado.
-
-Certifique-se de instalar o certificado SSL (``/etc/nginx/colab.crt``) e sua
-chave privada (``/etc/nginx/colab.key``).
-
-Reinicie o serviço do Nginx com o comando: ``sudo service nginx restart``.
-
-
-Colab
-+++++
-
-Edite o arquivo ``/etc/colab/settings.yaml`` e adicione o nome e e-mail dos administradores do sistema:
-
-.. code-block:: yaml
-
-   ## System admins
-   ADMINS: &admin
-     -
-       - John Foo
-       - john@example.com
-	 -
-	   - Mary Bar
-	   - mary@example.com
-
-   MANAGERS: *admin
-
-
-Edite o arquivo ``/etc/colab/settings.yaml`` e configure a URL principal da aplicação, quais hosts deverão aceitar requisições e quais hosts poderão ser utilizadas para que o login seja efetuado. Exemplo:
-
-.. code-block:: yaml
-
-   SITE_URL: 'https://beta.softwarepublico.gov.br'
-
-   ALLOWED_HOSTS:
-     - beta.softwarepublico.gov.br
-
-   BROWSERID_AUDIENCES:
-     - http://beta.softwarepublico.gov.br
-     - https://beta.softwarepublico.gov.br
-
-
-Edite o arquivo ``/etc/colab/settings.yaml`` e configure o endereço que será utilizado no FROM dos e-mails enviados pelo Colab. Veja o exemplo:
-
-.. code-block:: yaml
-
-   COLAB_FROM_ADDRESS: '"Portal do Software Publico" <noreply@beta.softwarepublico.gov.br>'
-   SERVER_EMAIL: '"Portal do Software Publico" <noreply@beta.softwarepublico.gov.br>'
-
-
-Edite o arquivo ``/etc/colab/settings.yaml`` e configure o endereço das ferramentas a serem integradas ao Colab. Veja o exemplo:
-
-.. code-block:: yaml
-
-   PROXIED_APPS:
-      gitlab:
-	 upstream: 'http://localhost:8080/gitlab'
-      noosfero:
-	 upstream: 'http://localhost:8090/noosfero'
-
-
-Após editar todos os arquivos desejados reinicie o processo do Colab com
-utilizando o comando ``service colab restart``.
-
-
-Gitlab
-++++++
-
-Edite o arquivo ``/etc/gitlab/gitlab.yml`` acrescentando o atributo
-relative_url_root após a linha ``email_from: example@example.com``. 
-Veja o exemplo a seguir:
-
-.. code-block:: yaml
-
-   email_from:example@example.com
-   relative_url_root: /gitlab
-
-
-Descomente a linha a seguir no arquivo ``/etc/gitlab/unicorn.rb``, veja o exemplo:
-
-.. code-block:: ruby
-
-   ENV['RAILS_RELATIVE_URL_ROOT'] = "/gitlab"
-
-
-Altere o atributo gitlab_url no arquivo ``/etc/gitlab-shell/config.yml``, acrescentando /gitlab a url existente. Veja o exemplo:
-
-.. code-block:: yaml
-
-   gitlab_url: "http://localhost:8080/gitlab"
-
-
-Descomente a linha a seguir no arquivo ``/usr/lib/gitlab/config/application.rb``, veja o exemplo:
-
-.. code-block:: ruby
-
-   config.relative_url_root = "/gitlab"
-
-
-Após a configuração acima ter sido feita o serviço do gitlab precisa ser reiniciado utilizando o comando ``service gitlab restart``.
-
-Noosfero
-++++++++
-
-Edite o arquivo ``/etc/noosfero/thin.yml``, e adicione uma linha com o
-seguinte conteúdo:
-
-.. code-block:: yaml
-
-   prefix: /social
-
-Crie/edite o arquivo ``/etc/default/noosfero`` e adicione a seguinte
-linha:
-
-.. code-block:: ruby
-
-   export RAILS_RELATIVE_URL_ROOT=/social
-
-Reinicie o serviço:
-
-.. code-block:: sh
-
-   $ sudo service noosfero restart
-
-Mailman
-+++++++
-
-Edite o arquivo de configuração do `mailman` em
-``/etc/mailman/mm_cfg.py``, e ajuste os seguintes valores:
-
-.. code-block:: python
-
-   DEFAULT_EMAIL_HOST = 'listas.softwarepublico.gov.br'
-   MTA = None
-   POSTFIX_STYLE_VIRTUAL_DOMAINS = ['listas.softwarepublico.gov.br']
-
-Crie a lista de discussão default, necessária para a inicialização do
-serviço. Substitua ``USER@DOMAIN.COM`` pelo email a ser usado como
-administrador do `mailman`, e ``PASSWORD`` pela senha de administração do
-`mailman`.
-
-.. code-block:: sh
-
-   $ sudo -u mailman /usr/lib/mailman/bin/newlist --quiet mailman USER@DOMAIN.COM PASSWORD
-   $ sudo service mailman restart
-
-
-Postfix
-+++++++
-
-Configure o postfix:
-
-.. code-block:: sh
-
-   $ sudo postconf relay_domains=listas.softwarepublico.gov.br
-   $ sudo postconf transport_maps=hash:/etc/postfix/transport
-
-Crie/edite ``/etc/postfix/transport`` com o seguinte conteúdo:
-
-.. code-block:: sh
-
-   listas.softwarepublico.gov.br mailman:
-
-
-Faça o download do arquivo :download:`postfix-to-mailman-centos.py` e salve no
-diretório ``/etc/postfix``, e altere as permissões para tornar o arquivo
-executável:
-
-.. code-block:: sh
-
-   $ sudo chmod +x /etc/postfix/postfix-to-mailman-centos.py
-
-Adicione o seguinte conteúdo no final do arquivo ``/etc/postfix/master.cf``:
-
-::
-
-   mailman   unix  -       n       n       -       -       pipe
-     flags=FR user=mailman:mailman
-     argv=/etc/postfix/postfix-to-mailman-centos.py ${nexthop} ${user}
-
-Gere o banco de dados para consulta, e reinicie o serviço:
-
-.. code-block:: sh
-
-   $ sudo postmap /etc/postfix/transport
-   $ sudo service postfix restart
-
-Inicie o serviço do mailman-api:
-
-.. code-block:: sh
-
-   $ sudo service mailman-api start
-
-
-Habilitar inicialização automática dos serviços
-+++++++++++++++++++++++++++++++++++++++++++++++
-
-Para permitir que os serviços iniciem automaticamente, execute os comandos
-abaixo:
-
-.. code-block:: sh
-
-   $ sudo systemctl enable mailman
-   $ sudo systemctl enable mailman-api
-   $ sudo systemctl enable nginx
-   $ sudo systemctl enable colab
-   $ sudo systemctl enable noosfero
-   $ sudo chkconfig --add gitlab
-   $ sudo chkconfig --add solr
@@ -0,0 +1,2 @@
+Manutenção
+==========
@@ -2,3 +2,8 @@ desc &#39;Builds documentation&#39;
 task :doc do
   sh 'make -C docs/ html'
 end
+
+desc 'Removes generated files'
+task :clean do
+  sh 'make -C docs/ clean'
+end
@@ -80,7 +80,7 @@ if [ &quot;$1&quot; = &#39;--doc&#39; ]; then
   }
   header() {
     echo "$1"
-    echo '=============='
+    echo '..............'
     echo
     echo '.. list-table::'
     echo '   :header-rows: 1'
@@ -93,11 +93,6 @@ if [ &quot;$1&quot; = &#39;--doc&#39; ]; then
     echo
   }
   (
-    echo
-    echo "Entradas de DNS necessárias"
-    echo '---------------------------'
-    echo
-    echo
     header 'DNS(A)'
     test_dns_web
     test_dns_lists
	@@ -44,7 +44,7 @@ master_doc = 'index'		@@ -44,7 +44,7 @@ master_doc = 'index'
44		44
45	# General information about the project.	45	# General information about the project.
46	project = u'softwarepublico'	46	project = u'softwarepublico'
47	-copyright = u'2014, Universidade de Brasília - UnB. Documentação licenciada sob a Licença Creative Commons Atribuição-CompartilhaIgual 4.0 Internacional'	47	+copyright = u'2014-2015, Universidade de Brasília - UnB. Documentação licenciada sob a Licença Creative Commons Atribuição-CompartilhaIgual 4.0 Internacional'
48		48
49	# The version info for the project you're documenting, acts as replacement for	49	# The version info for the project you're documenting, acts as replacement for
50	# \|version\| and \|release\|, also used in various other places throughout the	50	# \|version\| and \|release\|, also used in various other places throughout the
	@@ -57,7 +57,7 @@ release = '2.0'		@@ -57,7 +57,7 @@ release = '2.0'
57		57
58	# The language for content autogenerated by Sphinx. Refer to documentation	58	# The language for content autogenerated by Sphinx. Refer to documentation
59	# for a list of supported languages.	59	# for a list of supported languages.
60	-#language = None	60	+language = 'pt_BR'
61		61
62	# There are two options for replacing \|today\|: either, you set today to some	62	# There are two options for replacing \|today\|: either, you set today to some
63	# non-false value, then it is used:	63	# non-false value, then it is used:
	@@ -197,7 +197,7 @@ latex_elements = {		@@ -197,7 +197,7 @@ latex_elements = {
197	# author, documentclass [howto, manual, or own class]).	197	# author, documentclass [howto, manual, or own class]).
198	latex_documents = [	198	latex_documents = [
199	('index', 'softwarepublico.tex',	199	('index', 'softwarepublico.tex',
200	- u'Documentação - Software Público Brasileiro (SPB)',	200	+ u'Software Público Brasileiro: Manual de Operação',
201	u'Universidade de Brasília', 'manual'),	201	u'Universidade de Brasília', 'manual'),
202	]	202	]
203		203
	@@ -1,96 +0,0 @@	@@ -1,96 +0,0 @@
1	-
2	-.. _dependencies:
3	-
4	-Dependências
5	-============
6	-
7	-O repositório do SPB contém os pacotes que não são nativos do Sistema
8	-Operacional onde o mesmo o sistema do Portal do Software Público deve ser
9	-instalado. Esse repositório contém os pacotes referentes ao Bottle, Mailman-api,
10	-Solr, Colab e às dependências do Colab (pacote Colab-deps).
11	-
12	-Colab
13	-----------
14	-Esse pacote, contém o sistema Colab. O processo de
15	-criação desse pacote depende do pacote `python-virtualenv`, além de um
16	-conjunto de dependências python, contidos no pacote `colab-deps`, descrito na
17	-próxima seção. O processo de instalação desse pacote requer uma instalação
18	-prévia do pacote `colab-deps`, que é instalado automaticamente se o repositório
19	-do mesmo estiver disponível no conjunto de repositórios do `yum`.
20	-
21	-Colab-deps
22	-----------
23	-Este pacote contém as dependências python do Colab. Tais dependências foram
24	-encapsuladas em um ambiente virtual python (`python-virtualenv`), permitindo uma
25	-maior independência e, consequentemente, compatibilidade com o Sistema
26	-Operacional no qual o pacote seja instalado. Esse pacote é composto pelas
27	-ferramentas listadas a seguir.
28	-
29	-* Chardet
30	-* Django
31	-* Django-browserid
32	-* Django-cliauth
33	-* Django-common
34	-* Django-conversejs
35	-* Django-haystack
36	-* Django-hitcounter
37	-* Django-i18n-model
38	-* Django-mobile
39	-* Django-mptt
40	-* Django-piston
41	-* Django-revproxy
42	-* Django-taggit
43	-* Django-tastypie
44	-* Dpaste
45	-* Etiquetando
46	-* Eventlet
47	-* Fancy_tag
48	-* Feedzilla
49	-* Grab
50	-* Gunicorn
51	-* Html2text
52	-* Lorem-ipsum-generator
53	-* Lxml
54	-* Paste
55	-* Pip
56	-* Poster
57	-* Psycopg2
58	-* Pure-sasl
59	-* Pygments
60	-* Pysolr
61	-* Python-dateutil
62	-* Python-memcached
63	-* Python-mimeparse
64	-* PyYAML
65	-* Raven
66	-* Repoze.lru
67	-* Requests
68	-* Setuptools
69	-* Six
70	-* Sleekxmpp
71	-* South
72	-* Stemming
73	-* Tornado
74	-* Transliterate
75	-
76	-
77	-Mailman-api
78	------------
79	-
80	-Esse pacote contém o Mailman-api. Esta ferramenta python possui como
81	-dependência os pacotes Bottle e python. Como o Bottle não é provido
82	-nativamente pelo CentOS 7, foi necessário empacotá-lo separadamente.
83	-
84	-Bottle
85	------------
86	-
87	-Esse pacote contém a ferramenta Bottle, um framowork web escrito em
88	-python, e requisito para a utilização da ferramenta Mailman-api. Este pacote
89	-possui como dependência o pacote python, que está disponível nativamente no
90	-CentOS.
91	-
92	-Solr
93	-----
94	-Esse pacote contém a ferramenta python Bottle, e integra o conjunto de
95	-ferramentas do SPB. Sua instalação requer o pacote Java, que já existe
96	-nativamente no CentOS.
@@ -0,0 +1,2 @@		@@ -0,0 +1,2 @@
	1	+Gestão do firewall
	2	+==================
@@ -0,0 +1,4 @@		@@ -0,0 +1,4 @@
	1	+Implantação
	2	+===========
	3	+
	4	+.. include:: dns.rst
	@@ -1,403 +0,0 @@	@@ -1,403 +0,0 @@
1	-Instalação
2	-==========
3	-
4	-.. Descrição dos pacotes e listagem das dependências de cada pacote
5	-
6	-Para instalação das ferramentas que compõem o Software Público, é necessária a
7	-instalação de um conjunto de pacotes RPM. Um pacote RPM consiste em uma coleção
8	-de uma ou mais ferramentas que permite um meio automático de instalação,
9	-atualização, configuração e remoção de softwares.
10	-
11	-O processo de instalação aqui descrito permite a instalação e configuração
12	-desses pacotes em uma máquina com o Sistema Operacional CentOS 7 instalado e
13	-atualizado. Os pacotes a seguir já são fornecidos nativamente pelo Sistema
14	-Operacional, não sendo necessária uma configuração adicional para a
15	-instalação dos mesmos.
16	-
17	-* Mailman
18	-* Nginx
19	-* PostgreSQL Server
20	-
21	-Somados a esses, alguns pacotes não fornecidos nativamente também são
22	-necessários. Os mesmos estão listados a seguir.
23	-
24	-* Noosfero
25	-* Gitlab
26	-* Gitlab-deps
27	-* Solr
28	-* Colab
29	-* Colab-deps
30	-* Mailman-api
31	-
32	-Para disponibilizar cada pacote não nativo do CentOS 7, fez-se um levantamento
33	-das dependências de cada ferramenta empacotada, bem como do processo de
34	-instalação de cada uma, de modo a automatizar esse processo.
35	-A seção :ref:`dependencies` descreve brevemente o levantamento de dependências
36	-feito.
37	-
38	-
39	-Repositório do SPB
40	--------------------
41	-
42	-.. Configuração do repositório yum em /etc/yum.repos.d
43	-
44	-Para instalação dos pacotes existentes no repositório do SPB através do
45	-gerenciador de instalação e remoção de pacotes do CentOS (o Yum), é preciso
46	-adicionar o arquivo de configuração desse repositório no diretório
47	-`/etc/yum.repos.d/` do Sistema Operacional onde o Portal do Software Público deve
48	-Procedimento:
49	-
50	-Os comandos a seguir devem ser executados via terminal, com permissões de super
51	-usuário do sistema.
52	-
53	-1. Instalar (caso não esteja instalado) o programa `wget`, para download das
54	- configurações de repositório
55	-
56	-::
57	-
58	- yum install -y wget
59	-
60	-2. Ir para o diretório `/etc/yum.repos.d/`
61	-
62	-::
63	-
64	- cd /etc/yum.repos.d/
65	-
66	-3. Fazer o download dos arquivos de configuração nesse diretório:
67	-
68	-::
69	-
70	- wget http://download.opensuse.org/repositories/isv:/spb:/colab/CentOS_7/isv:spb:colab.repo
71	- wget http://download.opensuse.org/repositories/isv:/spb:/mailman-api/CentOS_7/isv:spb:mailman-api.repo
72	- wget http://download.opensuse.org/repositories/isv:/spb:/gitlab/CentOS_7/isv:spb:gitlab.repo
73	-
74	-4. Instalar repositório para instalação do servidor web Nginx:
75	-
76	-::
77	-
78	- rpm -i http://nginx.org/packages/centos/7/noarch/RPMS/nginx-release-centos-7-0.el7.ngx.noarch.rpm
79	-
80	-
81	-Instalação das Ferramentas (via pacote)
82	----------------------------------------
83	-
84	-.. Instalação dos pacotes via yum
85	-
86	-Após a configuração do repositório do SPB, todos os pacotes deverão estar
87	-disponíveis através do yum. Ainda que algumas dependências sejam tratadas
88	-automaticamente, o comportamento de alguns pacotes é dependente da ordem em que
89	-os mesmos são instalados. Portanto, deve-se executar a instalação na ordem
90	-especificada a seguir.
91	-Os comandos a seguir devem ser executados via terminal, com permissões de super
92	-usuário do sistema.
93	-
94	-Procedimento:
95	-
96	-1. Instalar o pacote PostreSQL Server
97	-
98	-::
99	-
100	- yum install -y postgresql-server
101	-
102	-2. Instalar o pacote do servidor de estrutura de dados Redis
103	-
104	-::
105	-
106	- yum install -y redis
107	-
108	-3. Instalar os pacotes do source forge Gitlab e gerenciador de repositórios
109	- Gitlab-shell
110	-
111	-::
112	-
113	- yum install -y gitlab gitlab-shell
114	-
115	-4. Instalar o pacote da ferramenta Noosfero
116	-
117	-::
118	-
119	- yum install -y noosfero
120	-
121	-5. Instalar o pacote da ferramenta de integração Colab
122	-
123	-::
124	-
125	- yum install -y colab
126	-
127	-6. Instalar o pacote do servidor web Nginx
128	-
129	-::
130	-
131	- yum install -y nginx
132	-
133	-Configurações
134	---------------
135	-
136	-
137	-Nginx
138	-+++++
139	-
140	-Para configurar o Nginx crie o arquivo ``/etc/nginx/conf.d/colab.conf`` com o conteúdo abaixo:
141	-
142	-.. code-block:: nginx
143	-
144	- upstream colab {
145	- server 127.0.0.1:8001 fail_timeout=10s;
146	- }
147	-
148	- server {
149	- listen *:80;
150	-
151	- server_name beta.softwarepublico.gov.br;
152	- return 301 https://$server_name$request_uri;
153	- }
154	-
155	- server {
156	- listen *:443 ssl;
157	-
158	- server_name beta.softwarepublico.gov.br;
159	-
160	- ssl on;
161	-
162	- ssl_certificate /etc/nginx/colab.crt;
163	- ssl_certificate_key /etc/nginx/colab.key;
164	- ssl_session_cache shared:SSL:10m;
165	- ssl_session_timeout 5m;
166	- ssl_protocols SSLv3 TLSv1 TLSv1.1 TLSv1.2;
167	- ssl_ciphers HIGH:!aNULL:!MD5;
168	- ssl_prefer_server_ciphers on;
169	-
170	- access_log /var/log/nginx/ssl-colab.access.log;
171	- error_log /var/log/nginx/ssl-colab.error.log;
172	-
173	- location /gitlab/assets/ {
174	- alias /var/lib/gitlab-assets/;
175	- }
176	-
177	- location / {
178	- root /usr/share/nginx/colab;
179	- try_files $uri @colab-app;
180	- }
181	-
182	- location @colab-app {
183	- proxy_pass http://colab;
184	- proxy_read_timeout 90;
185	- proxy_connect_timeout 90;
186	- proxy_redirect off;
187	- proxy_set_header Host $host;
188	- proxy_set_header X-Real-IP $remote_addr;
189	- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
190	- proxy_set_header X-Forwarded-Proto https;
191	- }
192	- }
193	-
194	-
195	-Substitua o domínio de exemplo ``beta.softwarepublico.gov.br`` pelo domínio
196	-desejado.
197	-
198	-Certifique-se de instalar o certificado SSL (``/etc/nginx/colab.crt``) e sua
199	-chave privada (``/etc/nginx/colab.key``).
200	-
201	-Reinicie o serviço do Nginx com o comando: ``sudo service nginx restart``.
202	-
203	-
204	-Colab
205	-+++++
206	-
207	-Edite o arquivo ``/etc/colab/settings.yaml`` e adicione o nome e e-mail dos administradores do sistema:
208	-
209	-.. code-block:: yaml
210	-
211	- ## System admins
212	- ADMINS: &admin
213	- -
214	- - John Foo
215	- - john@example.com
216	- -
217	- - Mary Bar
218	- - mary@example.com
219	-
220	- MANAGERS: *admin
221	-
222	-
223	-Edite o arquivo ``/etc/colab/settings.yaml`` e configure a URL principal da aplicação, quais hosts deverão aceitar requisições e quais hosts poderão ser utilizadas para que o login seja efetuado. Exemplo:
224	-
225	-.. code-block:: yaml
226	-
227	- SITE_URL: 'https://beta.softwarepublico.gov.br'
228	-
229	- ALLOWED_HOSTS:
230	- - beta.softwarepublico.gov.br
231	-
232	- BROWSERID_AUDIENCES:
233	- - http://beta.softwarepublico.gov.br
234	- - https://beta.softwarepublico.gov.br
235	-
236	-
237	-Edite o arquivo ``/etc/colab/settings.yaml`` e configure o endereço que será utilizado no FROM dos e-mails enviados pelo Colab. Veja o exemplo:
238	-
239	-.. code-block:: yaml
240	-
241	- COLAB_FROM_ADDRESS: '"Portal do Software Publico" <noreply@beta.softwarepublico.gov.br>'
242	- SERVER_EMAIL: '"Portal do Software Publico" <noreply@beta.softwarepublico.gov.br>'
243	-
244	-
245	-Edite o arquivo ``/etc/colab/settings.yaml`` e configure o endereço das ferramentas a serem integradas ao Colab. Veja o exemplo:
246	-
247	-.. code-block:: yaml
248	-
249	- PROXIED_APPS:
250	- gitlab:
251	- upstream: 'http://localhost:8080/gitlab'
252	- noosfero:
253	- upstream: 'http://localhost:8090/noosfero'
254	-
255	-
256	-Após editar todos os arquivos desejados reinicie o processo do Colab com
257	-utilizando o comando ``service colab restart``.
258	-
259	-
260	-Gitlab
261	-++++++
262	-
263	-Edite o arquivo ``/etc/gitlab/gitlab.yml`` acrescentando o atributo
264	-relative_url_root após a linha ``email_from: example@example.com``.
265	-Veja o exemplo a seguir:
266	-
267	-.. code-block:: yaml
268	-
269	- email_from:example@example.com
270	- relative_url_root: /gitlab
271	-
272	-
273	-Descomente a linha a seguir no arquivo ``/etc/gitlab/unicorn.rb``, veja o exemplo:
274	-
275	-.. code-block:: ruby
276	-
277	- ENV['RAILS_RELATIVE_URL_ROOT'] = "/gitlab"
278	-
279	-
280	-Altere o atributo gitlab_url no arquivo ``/etc/gitlab-shell/config.yml``, acrescentando /gitlab a url existente. Veja o exemplo:
281	-
282	-.. code-block:: yaml
283	-
284	- gitlab_url: "http://localhost:8080/gitlab"
285	-
286	-
287	-Descomente a linha a seguir no arquivo ``/usr/lib/gitlab/config/application.rb``, veja o exemplo:
288	-
289	-.. code-block:: ruby
290	-
291	- config.relative_url_root = "/gitlab"
292	-
293	-
294	-Após a configuração acima ter sido feita o serviço do gitlab precisa ser reiniciado utilizando o comando ``service gitlab restart``.
295	-
296	-Noosfero
297	-++++++++
298	-
299	-Edite o arquivo ``/etc/noosfero/thin.yml``, e adicione uma linha com o
300	-seguinte conteúdo:
301	-
302	-.. code-block:: yaml
303	-
304	- prefix: /social
305	-
306	-Crie/edite o arquivo ``/etc/default/noosfero`` e adicione a seguinte
307	-linha:
308	-
309	-.. code-block:: ruby
310	-
311	- export RAILS_RELATIVE_URL_ROOT=/social
312	-
313	-Reinicie o serviço:
314	-
315	-.. code-block:: sh
316	-
317	- $ sudo service noosfero restart
318	-
319	-Mailman
320	-+++++++
321	-
322	-Edite o arquivo de configuração do `mailman` em
323	-``/etc/mailman/mm_cfg.py``, e ajuste os seguintes valores:
324	-
325	-.. code-block:: python
326	-
327	- DEFAULT_EMAIL_HOST = 'listas.softwarepublico.gov.br'
328	- MTA = None
329	- POSTFIX_STYLE_VIRTUAL_DOMAINS = ['listas.softwarepublico.gov.br']
330	-
331	-Crie a lista de discussão default, necessária para a inicialização do
332	-serviço. Substitua ``USER@DOMAIN.COM`` pelo email a ser usado como
333	-administrador do `mailman`, e ``PASSWORD`` pela senha de administração do
334	-`mailman`.
335	-
336	-.. code-block:: sh
337	-
338	- $ sudo -u mailman /usr/lib/mailman/bin/newlist --quiet mailman USER@DOMAIN.COM PASSWORD
339	- $ sudo service mailman restart
340	-
341	-
342	-Postfix
343	-+++++++
344	-
345	-Configure o postfix:
346	-
347	-.. code-block:: sh
348	-
349	- $ sudo postconf relay_domains=listas.softwarepublico.gov.br
350	- $ sudo postconf transport_maps=hash:/etc/postfix/transport
351	-
352	-Crie/edite ``/etc/postfix/transport`` com o seguinte conteúdo:
353	-
354	-.. code-block:: sh
355	-
356	- listas.softwarepublico.gov.br mailman:
357	-
358	-
359	-Faça o download do arquivo :download:`postfix-to-mailman-centos.py` e salve no
360	-diretório ``/etc/postfix``, e altere as permissões para tornar o arquivo
361	-executável:
362	-
363	-.. code-block:: sh
364	-
365	- $ sudo chmod +x /etc/postfix/postfix-to-mailman-centos.py
366	-
367	-Adicione o seguinte conteúdo no final do arquivo ``/etc/postfix/master.cf``:
368	-
369	-::
370	-
371	- mailman unix - n n - - pipe
372	- flags=FR user=mailman:mailman
373	- argv=/etc/postfix/postfix-to-mailman-centos.py ${nexthop} ${user}
374	-
375	-Gere o banco de dados para consulta, e reinicie o serviço:
376	-
377	-.. code-block:: sh
378	-
379	- $ sudo postmap /etc/postfix/transport
380	- $ sudo service postfix restart
381	-
382	-Inicie o serviço do mailman-api:
383	-
384	-.. code-block:: sh
385	-
386	- $ sudo service mailman-api start
387	-
388	-
389	-Habilitar inicialização automática dos serviços
390	-+++++++++++++++++++++++++++++++++++++++++++++++
391	-
392	-Para permitir que os serviços iniciem automaticamente, execute os comandos
393	-abaixo:
394	-
395	-.. code-block:: sh
396	-
397	- $ sudo systemctl enable mailman
398	- $ sudo systemctl enable mailman-api
399	- $ sudo systemctl enable nginx
400	- $ sudo systemctl enable colab
401	- $ sudo systemctl enable noosfero
402	- $ sudo chkconfig --add gitlab
403	- $ sudo chkconfig --add solr
	@@ -2,3 +2,8 @@ desc 'Builds documentation'		@@ -2,3 +2,8 @@ desc 'Builds documentation'
2	task :doc do	2	task :doc do
3	sh 'make -C docs/ html'	3	sh 'make -C docs/ html'
4	end	4	end
		5	+
		6	+desc 'Removes generated files'
		7	+task :clean do
		8	+ sh 'make -C docs/ clean'
		9	+end