diff --git a/docs/arquitetura.rst b/docs/arquitetura.rst new file mode 100644 index 0000000..62f0138 --- /dev/null +++ b/docs/arquitetura.rst @@ -0,0 +1,2 @@ +Arquitetura +=========== diff --git a/docs/backup.rst b/docs/backup.rst new file mode 100644 index 0000000..84f0de0 --- /dev/null +++ b/docs/backup.rst @@ -0,0 +1,4 @@ +Backup +====== + + diff --git a/docs/conf.py b/docs/conf.py index 704fcee..be2c80d 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -44,7 +44,7 @@ master_doc = 'index' # 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 = '2.0' # 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'), ] diff --git a/docs/dependencies.rst b/docs/dependencies.rst deleted file mode 100644 index ddd6616..0000000 --- a/docs/dependencies.rst +++ /dev/null @@ -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. diff --git a/docs/firewall.rst b/docs/firewall.rst new file mode 100644 index 0000000..98973e6 --- /dev/null +++ b/docs/firewall.rst @@ -0,0 +1,2 @@ +Gestão do firewall +================== diff --git a/docs/implantacao.rst b/docs/implantacao.rst new file mode 100644 index 0000000..31590e2 --- /dev/null +++ b/docs/implantacao.rst @@ -0,0 +1,4 @@ +Implantação +=========== + +.. include:: dns.rst diff --git a/docs/index.rst b/docs/index.rst index ac24e6c..97ad1cf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,40 +1,66 @@ - -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 diff --git a/docs/install.rst b/docs/install.rst deleted file mode 100644 index ea17f07..0000000 --- a/docs/install.rst +++ /dev/null @@ -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" ' - SERVER_EMAIL: '"Portal do Software Publico" ' - - -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 diff --git a/docs/manutencao.rst b/docs/manutencao.rst new file mode 100644 index 0000000..96786d6 --- /dev/null +++ b/docs/manutencao.rst @@ -0,0 +1,2 @@ +Manutenção +========== diff --git a/tasks/doc.rake b/tasks/doc.rake index 643bf55..ee23c0e 100644 --- a/tasks/doc.rake +++ b/tasks/doc.rake @@ -2,3 +2,8 @@ desc 'Builds documentation' task :doc do sh 'make -C docs/ html' end + +desc 'Removes generated files' +task :clean do + sh 'make -C docs/ clean' +end diff --git a/test/dns_test.sh b/test/dns_test.sh index deb9f39..1ccc0dc 100644 --- a/test/dns_test.sh +++ b/test/dns_test.sh @@ -80,7 +80,7 @@ if [ "$1" = '--doc' ]; then } header() { echo "$1" - echo '==============' + echo '..............' echo echo '.. list-table::' echo ' :header-rows: 1' @@ -93,11 +93,6 @@ if [ "$1" = '--doc' ]; then echo } ( - echo - echo "Entradas de DNS necessárias" - echo '---------------------------' - echo - echo header 'DNS(A)' test_dns_web test_dns_lists -- libgit2 0.21.2