From 18e5d3c5969f319e934bb26eedcf7865e77fd314 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 14:07:27 +0000 Subject: Adjust the documentation based on the feedback received during the code review --- diff --git a/doc/Install.rst b/doc/Install.rst index 6c65988..4572f9d 100644 --- a/doc/Install.rst +++ b/doc/Install.rst @@ -16,7 +16,8 @@ Here as well there are two ways of obtaining the RPM: * From the main repositories Pagure is packaged for Fedora since Fedora 21 and is available for RHEL and -its derivative via the `EPEL repository <>`. So installing it is as easy as: +its derivative via the `EPEL repository `. +So installing it is as easy as: :: dnf install pagure pagure-milters pagure-ev @@ -30,7 +31,8 @@ The ``pagure`` package contains the core of the application and the doc server. (See the ``Overview`` page for a global overview of the structure of the project). -The ``pagure-milters`` package contains, as the name says, the milter. +The ``pagure-milters`` package contains, as the name says, the milter (a +mail filter to hook into a MTA). The ``pagure-ev`` package contains the eventsource server. @@ -58,7 +60,7 @@ Simply follow these steps: This will build pagure from the version present in your clone. -Once, the RPM is installed, the services ``pagure_milter`` and ``pagure_ev`` +Once, the RPM is installed the services ``pagure_milter`` and ``pagure_ev`` are ready to be used but the database and the web-application parts still need to be configured. @@ -106,7 +108,7 @@ To install pagure via this mechanism simply follow these steps: Set-up pagure ------------- -Once pagure's files are installed, you still need to set-up some things. +Once pagure's files are installed, you still need to set up some things. * Create the folder release @@ -152,11 +154,11 @@ Adjust it for your needs. * Configure the WSGI file -If install by RPM, you will find an example WSGI file at: +If you installed by RPM, you will find an example WSGI file at: ``/usr/share/pagure/pagure.wsgi`` and ``/usr/share/pagure/docs_pagure.wsgi`` for the doc server. -If not install by RPM, these files are present in the sources at: +If you did not install by RPM, these files are present in the sources at: ``files/pagure.wsgi`` and ``files/doc_pagure.wsgi``. Adjust them for your needs @@ -164,13 +166,13 @@ Adjust them for your needs * Give apache permission to read the repositories owned by the ``git`` user. -The web application run under the ``git`` user name, the same username as -your gitolite user, but apache itself runs under the ``apache`` (or -``httpd2``) user. So apache by default, apache will not be allowed to read -git repositories created and managed by gitolite. +For the sake of this document, we assume that the web application runs under +the ``git`` user, the same user as your gitolite user, but apache itself +runs under the ``httpd`` (or ``apache2``) user. So by default, apache +will not be allowed to read git repositories created and managed by gitolite. To give apache this permission (required to make git clone via http work), -we use facl +we use file access control lists (aka FACL): :: setfacl -m user:apache:rx --default setfacl -Rdm user:apache:rx /srv/git diff --git a/doc/Install_evs.rst b/doc/Install_evs.rst index 1bf81a9..4d2c4ad 100644 --- a/doc/Install_evs.rst +++ b/doc/Install_evs.rst @@ -11,17 +11,16 @@ Configure your system The eventsource server is easy to set-up. -* Installed the required dependencies +* Install the required dependencies :: python-redis python-trollius python-trollius-redis - systemd +..note: We ship a systemd unit file for pagure_milter but we welcome patches + for scripts for other init systems. -..note: This last one is necessary if you want to use the service file provided. - Otherwise, you will have to write your own. * Install the files of the SSE server as follow: @@ -30,7 +29,7 @@ The eventsource server is easy to set-up. +========================================+=====================================================+ | ``ev-server/pagure-stream-server.py`` | ``/usr/libexec/pagure-ev/pagure-stream-server.py`` | +----------------------------------------+-----------------------------------------------------+ -| ``ev-server/pagure_ev.service`` | ``/usr/lib/systemd/system/pagure_ev.service`` | +| ``ev-server/pagure_ev.service`` | ``/etc/systemd/system/pagure_ev.service`` | +----------------------------------------+-----------------------------------------------------+ The first file is the script of the SSE server itself. diff --git a/doc/Install_milter.rst b/doc/Install_milter.rst index 4992df9..1578ef5 100644 --- a/doc/Install_milter.rst +++ b/doc/Install_milter.rst @@ -1,23 +1,23 @@ Installing pagure's milter ========================== -A milter is a script that is ran by a MTA upon receiving an email via either -a network or an unix socket. +A milter is a script that is ran by a Mail Transfer Agent (`MTA +`_) +upon receiving an email via either a network or an unix socket. If you want more information feel free to check out the corresponding page -on wikipedia `https://en.wikipedia.org/wiki/Milter `_. +on wikipedia: `https://en.wikipedia.org/wiki/Milter `_. Configure your system --------------------- -* Installed the required dependencies +* Install the required dependencies :: python-pymilter - systemd -..note: This last one is necessary if you want to use the service file provided. - Otherwise, you will have to write your own. +..note: We ship a systemd unit file for pagure_milter but we welcome patches + for scripts for other init systems. ..note: It also requires a MTA, we used postfix. @@ -30,7 +30,7 @@ This can be done in ``/etc/aliases``, for example: reply: /dev/null -* Activate the ability of you MTA, to split users based on the character ``+``. +* Activate the ability of your MTA, to split users based on the character ``+``. This way all the emails sent to ``reply+...@example.com`` will be forwarded to your alias for ``reply``. @@ -58,7 +58,7 @@ In postfix this is done via: +----------------------------------------+-------------------------------------------------+ | ``milters/milter_tempfile.conf`` | ``/usr/lib/tmpfiles.d/pagure-milter.conf`` | +----------------------------------------+-------------------------------------------------+ -| ``milters/pagure_milter.service`` | ``/usr/lib/systemd/system/pagure_milter.service`` | +| ``milters/pagure_milter.service`` | ``/etc/systemd/system/pagure_milter.service`` | +--------------------------------------+---------------------------------------------------+ The first file is the script of the milter itself. diff --git a/doc/index.rst b/doc/index.rst index 408f67b..3d18135 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -10,6 +10,9 @@ Features: * Collaboration: Fork a project and make a pull-request * Integration: Create pull-request from a fork hosted somewhere else than in pagure +* Async: Sources, doc, ticket and pull-requests meta-data are available in + the web interface but also in git repos which can thus be cloned and + change locally. * ``Freedom``: Pagure is fully Free and Open-Source Software! diff --git a/doc/overview.rst b/doc/overview.rst index 18df8aa..1ca818e 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -1,7 +1,7 @@ Overview ======== -Pagure is split over multiple components, each having their interest and all +Pagure is split over multiple components, each having their purpose and all but one (the core application) being optional. These components are: @@ -13,8 +13,7 @@ Pagure core application ----------------------- The core application is the flask application interacting with gitolite to -provide a web UI to these git repositories as well as tickets and -pull-requests. +provide a web UI to the git repositories as well as tickets and pull-requests. This is the main application for the forge. @@ -26,7 +25,7 @@ for security concern, displaying information directly provided by the user without a clear/safe way of filtering for un-safe script or hacks is a security hole. For this reason we also strongly encourage anyone wanting to deploy their -own instance of pagure with the doc server, to run this application on an +own instance of pagure with the doc server, to run this application on a completely different domain name (not just a sub-domain) in order to reduce the cross-site forgery risks.