From e68ff382f81e89d9b221856630a22acba0fe3454 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:47:53 +0000 Subject: [PATCH 1/23] Expand the documentation by adding an overview of pagure structure --- diff --git a/doc/overview.rst b/doc/overview.rst new file mode 100644 index 0000000..cff15db --- /dev/null +++ b/doc/overview.rst @@ -0,0 +1,59 @@ +Overview +======== + +Pagure is split over multiple components, each having their interest and all +but one (the core application) being optional. + +These components are: + +.. contents:: + + +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. +This is the main application for the forge. + + +Pagure doc server +----------------- + +While integrated into the main application at first, it has been split out +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 +completely different domain name (not just a sub-domain) in order to reduce +the cross-site forgery risks. + +Pagure can be run just fine without the doc server, all you need to do is to +**not** define the variable ``DOC_APP_URL`` in the configuration file. + + +Pagure milter +------------- + +The milter is a script, receiving an email as input and performing an action +with it. + +In the case of pagure, the milter is used to allow replying on a comment +of a ticket or a pull-request by directly replying to the notification sent. +No need to go to the page anymore to reply to a comment someone made. + +The milter integrates with an smtp server such as postfix or sendmail that +you will have running and have access to in order to change its configuration. + + +Pagure EventSource Server +------------------------- + +Eventsource or Server Sent Events are messages sent from a server to a browser. + +For pagure this technology is used to allow live-refreshing of a page when +someone is viewing it. For example, while you are reading a ticket if someone +comments on it, the comment will automatically show up on the page without +the need for you to reload the entire page. From fab11582b58fd6fcfb9244e7046d065e82eef157 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:47:53 +0000 Subject: [PATCH 2/23] Adjust wording from smtp server to MTA --- diff --git a/doc/overview.rst b/doc/overview.rst index cff15db..18df8aa 100644 --- a/doc/overview.rst +++ b/doc/overview.rst @@ -44,8 +44,8 @@ In the case of pagure, the milter is used to allow replying on a comment of a ticket or a pull-request by directly replying to the notification sent. No need to go to the page anymore to reply to a comment someone made. -The milter integrates with an smtp server such as postfix or sendmail that -you will have running and have access to in order to change its configuration. +The milter integrates with a MTA such as postfix or sendmail that you will +have running and have access to in order to change its configuration. Pagure EventSource Server From 7a137ae073b6756b69ad95270f26463762849fc1 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:47:53 +0000 Subject: [PATCH 3/23] Add a documentation on how to install the milter --- diff --git a/doc/Install_milter.rst b/doc/Install_milter.rst new file mode 100644 index 0000000..9340c4d --- /dev/null +++ b/doc/Install_milter.rst @@ -0,0 +1,43 @@ +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. + +If you want more information feel free to check out the corresponding page +on wikipedia `https://en.wikipedia.org/wiki/Milter `_. + +Configure your system +--------------------- + +* Create an alias ``reply`` + +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 ``+``. + This way all the emails sent to ``reply+...@example.com`` will be forwarded + to your alias for ``reply``. + + +In postfix this is done via: +:: + + recipient_delimiter = + + +* Hook the milter in the MTA + +In postfix this is done via: +:: + + non_smtpd_milters = unix:/var/run/pagure/paguresock + smtpd_milters = unix:/var/run/pagure/paguresock + +* Activate the service and ensure it's started upon boot: +:: + + systemctl enable pagure_milter + systemctl start pagure_milter From df708b46d5b063be76a05827e848f06581c3a17f Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:47:53 +0000 Subject: [PATCH 4/23] Add documentation on how to install pagure's eventsource server --- diff --git a/doc/Install_evs.rst b/doc/Install_evs.rst new file mode 100644 index 0000000..bcce802 --- /dev/null +++ b/doc/Install_evs.rst @@ -0,0 +1,40 @@ +Installing pagure's EventSource server +====================================== + +Eventsource or Server Sent Events are messages sent from a server to a web +browser. It allows to refresh a page "live", ie, without the need to reload +it entirely. + + +Configure your system +--------------------- + +The eventsource server is easy to set-up. + +* Installed the required dependencies + +:: + + python-redis + python-trollius + python-trollius-redis + systemd + +..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: + ++----------------------------------------+-----------------------------------------------------+ +| Source | Destination | ++========================================+=====================================================+ +| ``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`` | ++----------------------------------------+-----------------------------------------------------+ + +* Finally, activate the service and ensure it's started upon boot: +:: + + systemctl enable pagure_ev + systemctl start pagure_ev From 9fdcc8e6f804089c2bafce81be64b81020ba568f Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:47:53 +0000 Subject: [PATCH 5/23] Be consistent in the formatting and explain what the files installed are --- diff --git a/doc/Install_evs.rst b/doc/Install_evs.rst index bcce802..c0e0853 100644 --- a/doc/Install_evs.rst +++ b/doc/Install_evs.rst @@ -12,7 +12,6 @@ Configure your system The eventsource server is easy to set-up. * Installed the required dependencies - :: python-redis @@ -20,6 +19,7 @@ The eventsource server is easy to set-up. python-trollius-redis systemd + ..note: This last one is necessary if you want to use the service file provided. Otherwise, you will have to write your own. @@ -33,6 +33,11 @@ The eventsource server is easy to set-up. | ``ev-server/pagure_ev.service`` | ``/usr/lib/systemd/system/pagure_ev.service`` | +----------------------------------------+-----------------------------------------------------+ +The first file is the script of the SSE server itself. + +The second file is the systemd service file. + + * Finally, activate the service and ensure it's started upon boot: :: From cb69ee0fa266007efe718f8fc724850f057e861d Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:47:53 +0000 Subject: [PATCH 6/23] Explain which files to install and where for the milter --- diff --git a/doc/Install_milter.rst b/doc/Install_milter.rst index 9340c4d..50985b6 100644 --- a/doc/Install_milter.rst +++ b/doc/Install_milter.rst @@ -36,6 +36,27 @@ In postfix this is done via: non_smtpd_milters = unix:/var/run/pagure/paguresock smtpd_milters = unix:/var/run/pagure/paguresock + +* Install the files of the milter as follow: + ++--------------------------------------+---------------------------------------------------+ +| Source | Destination | ++======================================+===================================================+ +| ``milters/comment_email_milter.py`` | ``/usr/share//pagure/comment_email_milter.py`` | ++----------------------------------------+-------------------------------------------------+ +| ``milters/milter_tempfile.conf`` | ``/usr/lib/tmpfiles.d/pagure-milter.conf`` | ++----------------------------------------+-------------------------------------------------+ +| ``milters/pagure_milter.service`` | ``/usr/lib/systemd/system/pagure_milter.service`` | ++--------------------------------------+---------------------------------------------------+ + +The first file is the script of the milter itself. + +The second file is a file specific for systemd and ensuring the temporary +folders needed by the milter are re-created if needed at each boot. + +The third file is the systemd service file. + + * Activate the service and ensure it's started upon boot: :: From 9664af5a23fa801ca8afbfd6c1cb3221f8c5a5b7 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:47:53 +0000 Subject: [PATCH 7/23] List the dependencies to install for the milter --- diff --git a/doc/Install_milter.rst b/doc/Install_milter.rst index 50985b6..4992df9 100644 --- a/doc/Install_milter.rst +++ b/doc/Install_milter.rst @@ -10,6 +10,18 @@ on wikipedia `https://en.wikipedia.org/wiki/Milter Date: Jul 28 2015 12:47:53 +0000 Subject: [PATCH 8/23] Adjust the spec file No need to install python-pymilter to build the milter package as the file is installed using %install We need to have systemd-devel for the ev package as we are treating with systemd files/service. --- diff --git a/files/pagure.spec b/files/pagure.spec index 4a9931d..a73e2c4 100644 --- a/files/pagure.spec +++ b/files/pagure.spec @@ -83,7 +83,6 @@ create/merge pull-requests across or within projects. %package milters Summary: Milter to integrate pagure with emails BuildArch: noarch -BuildRequires: python-pymilter BuildRequires: systemd-devel Requires: python-pymilter Requires(post): systemd @@ -103,6 +102,7 @@ This is useful for example to allow commenting on a ticket by email. Summary: EventSource server for pagure BuildArch: noarch +BuildRequires: systemd-devel Requires: python-redis Requires: python-trollius Requires: python-trollius-redis From ca7bb52f050781aa011d3afd3839909982db90e0 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:47:53 +0000 Subject: [PATCH 9/23] Adjust the URL and Source0 in the spec file --- diff --git a/files/pagure.spec b/files/pagure.spec index a73e2c4..723c6f6 100644 --- a/files/pagure.spec +++ b/files/pagure.spec @@ -7,8 +7,8 @@ Release: 1%{?dist} Summary: A git-centered forge License: GPLv2+ -URL: http://fedorahosted.org/pagure/ -Source0: https://fedorahosted.org/releases/p/a/pagure/%{name}-%{version}.tar.gz +URL: https://pagure.io/pagure +Source0: https://pagure.io/releases/pagure/%{name}-%{version}.tar.gz BuildArch: noarch From 4751deb20b014f03ba4fa8ea1996ef9c71befad1 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:47:53 +0000 Subject: [PATCH 10/23] Add a documentation on how to install pagure's web components --- diff --git a/doc/Install.rst b/doc/Install.rst new file mode 100644 index 0000000..98a2844 --- /dev/null +++ b/doc/Install.rst @@ -0,0 +1,85 @@ +Installing pagure +================= + +There are two ways to install pagure: + +* via the RPM package (recommanded if you are using a RPM-based linux distribution) +* via the setup.py + + + +Installing pagure via RPM +------------------------- + +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: +:: + + dnf install pagure pagure-milters pagure-ev + +or +:: + yum install pagure pagure-milters pagure-ev + +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-ev`` package contains the eventsource server. + +..note: The last two packages are optional, pagure would work fine without + them. + +* From the sources + +If you wish to run a newer version of pagure than what is in the repositories +you can easily rebuild it as RPM. + +Simply follow these steps: +# Clone the sources:: + git clone https://pagure.io/pagure.git + +# Go to the folder:: + cd pagure + +# Build a tarball of the latest version of pagure:: + python setup.py sdist + +# Build the RPM:: + rpmbuild -ta dist/pagure*.tar.gz + +This will build pagure from the version present in your clone. + + +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. + + + +Installing pagure via setup.py +------------------------------ + +Pagure includes in its sources a ``setup.py`` automatint the installation +of the web applications of pagure (ie: the core + the doc server). + + +To install pagure via this mechanism simply follow these steps: +# Clone the sources:: + git clone https://pagure.io/pagure.git + +# Go to the folder:: + cd pagure + +# Install the latest version of pagure:: + python setup.py build + sudo python setup.py install + +..note: To install the eventsource server or the milter, refer to their + respective documentations. From 33cc04d044f803f769face5d7aa33e957864a00d Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:47:53 +0000 Subject: [PATCH 11/23] Let's not forget to start redis if we want to have SSE work --- diff --git a/doc/Install_evs.rst b/doc/Install_evs.rst index c0e0853..1bf81a9 100644 --- a/doc/Install_evs.rst +++ b/doc/Install_evs.rst @@ -41,5 +41,7 @@ The second file is the systemd service file. * Finally, activate the service and ensure it's started upon boot: :: + systemctl enable redis + systemctl start redis systemctl enable pagure_ev systemctl start pagure_ev From c8389c8405a2cfab344ac4ffe9b69994fb0809bc Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:47:53 +0000 Subject: [PATCH 12/23] Install the additional files and explain what to do next --- diff --git a/doc/Install.rst b/doc/Install.rst index 98a2844..e7701f4 100644 --- a/doc/Install.rst +++ b/doc/Install.rst @@ -83,3 +83,91 @@ To install pagure via this mechanism simply follow these steps: ..note: To install the eventsource server or the milter, refer to their respective documentations. + +# Install the additional files as follow: + ++------------------------------+------------------------------------------+ +| Source | Destination | ++=============================+===========================================+ +| ``files/pagure.cfg.sample`` | ``/etc/pagure/pagure.cfg`` | ++------------------------------+------------------------------------------+ +| ``files/alembic.ini`` | ``/etc/pagure/alembic.ini`` | ++------------------------------+------------------------------------------+ +| ``files/pagure.conf`` | ``/etc/httpd/conf.d/pagure.conf`` | ++------------------------------+------------------------------------------+ +| ``files/pagure.wsgi`` | ``/usr/share/pagure/pagure.wsgi`` | ++------------------------------+------------------------------------------+ +| ``createdb.py`` | ``/usr/share/pagure/pagure_createdb.py`` | ++------------------------------+------------------------------------------+ + + + +Set-up pagure +------------- + +Once pagure's files are installed, you still need to set-up some things. + + +* Create the folder release + +This folder is used by project maintainers to upload the tarball of the +releases of their project. + +This folder must be accessible by the user under which the application is +running (in our case: ``git``). +:: + + mkdir -p /var/www/releases + chown git:git /var/www/releases + + +* Configure apache + +If installed by RPM, you will find an example apache configuration file +at: ``/etc/httpd/conf.d/pagure.conf``. + +If not installed by RPM, the example files is present in the sources at: +``files/pagure.conf``. + +Adjust it for your needs. + + +* Configure the WSGI file + +If install 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: +``files/pagure.wsgi`` and ``files/doc_pagure.wsgi``. + +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. + +To give apache this permission (required to make git clone via http work), +we use facl +:: + ... + setfacl -Rdm user:apache:rx /srv/git + setfacl -Rm user:apache:rx /srv/git + +Where ``/srv/git`` is the home of your gitolite user (which will thus need +to be adjusted for your configuration). + + +* Set up the configuration file of pagure + +This is an important step which concerns the file ``/etc/pagure/pagure.cfg``. +If you have installed pagure by RPM, this file is already there, otherwise +you can find an example one in the sources at: ``files/pagure.cfg.sample`` +that you will have to copy to the right location. + +Confer the ``Configuration`` section of this documentation for a full +explanation of all the options of pagure. From 84fcb431695fd9f32a1199eddc406488a3f37a0d Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:47:53 +0000 Subject: [PATCH 13/23] Fix formatting issue --- diff --git a/doc/Install.rst b/doc/Install.rst index e7701f4..5714db4 100644 --- a/doc/Install.rst +++ b/doc/Install.rst @@ -22,6 +22,7 @@ its derivative via the `EPEL repository <>`. So installing it is as easy as: dnf install pagure pagure-milters pagure-ev or + :: yum install pagure pagure-milters pagure-ev From 17b915efa59c0adbb4b4a3d3edde4bd27d3b6f58 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:47:53 +0000 Subject: [PATCH 14/23] Add a note about creating the folders for the git repos --- diff --git a/doc/Install.rst b/doc/Install.rst index 5714db4..ca80964 100644 --- a/doc/Install.rst +++ b/doc/Install.rst @@ -122,6 +122,23 @@ running (in our case: ``git``). chown git:git /var/www/releases +* Create the folders where the repos, forks and checkouts will be stored + +Pagure stores the sources of a project in a git repo, offers a place to +store the project's documentation in another repo, stores a JSON dump of all +issues and of all pull-requests in another two repos, and keeps a local +checkout of remote projects when asked to do remote pull-requests. +All these repositories are stored in different folders that must be +created manually. + +For example you can place them under ``/srv/git/repositories/`` which would +make ``/srv/git`` the home of your gitolite user. + +You would then create the folders with: +:: + mkdir /srv/git/repositories/{docs,forks,tickets,requests,checkouts} + + * Configure apache If installed by RPM, you will find an example apache configuration file From e7a0fb5d8df24a3a0e6bbad9f21bcd609f2f9702 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:53:27 +0000 Subject: [PATCH 15/23] Adjust the front page of pagure's documentation --- diff --git a/doc/index.rst b/doc/index.rst index 931137a..87e2d0e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -3,20 +3,21 @@ Pagure Pagure is a light-weight git-centered forge based on pygit2. -Currently, Pagure offers a decent web-interface for git repositories, a simple -ticket system and supports open collaboration by offering the possibility to -create new projects, fork existing ones and create/merge pull-requests across -or within projects. +Features: +* Open-sources: Web-interface for the git repositories +* Flexibility: Ability to create any project you want +* One place: Keep your documentation and tickets in pagure +* Collaboration: Fork a project and make a pull-request +* Integration: Create pull-request from a fork hosted somewhere else than in + pagure +* ``Freedom``: Pagure is fully Free and Open-Source Software! Resources: -- `Home page `_ +- `Home page `_ - `Github mirror `_ -- `Discussion mailing-list - `_ Contents: From 7013cc48ccbcd35d03b0b9c24890ca8da51c6f01 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 12:54:11 +0000 Subject: [PATCH 16/23] Pagure no longer serves git:// --- diff --git a/doc/development.rst b/doc/development.rst index 8da929e..bcc321e 100644 --- a/doc/development.rst +++ b/doc/development.rst @@ -8,7 +8,7 @@ Anonymous: :: - git clone git://pagure.io/pagure.git + git clone https://pagure.io/pagure.git Contributors: @@ -54,7 +54,7 @@ Run the server: :: ./runserver - + To get some profiling information you can also run it as: :: From 689ad9d389fbbecadab3a485c9a598800909767d Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 13:04:08 +0000 Subject: [PATCH 17/23] Specify the missing command to set the default acl --- diff --git a/doc/Install.rst b/doc/Install.rst index ca80964..18767c4 100644 --- a/doc/Install.rst +++ b/doc/Install.rst @@ -172,7 +172,7 @@ git repositories created and managed by gitolite. To give apache this permission (required to make git clone via http work), we use facl :: - ... + setfacl -m user:apache:rwx --default setfacl -Rdm user:apache:rx /srv/git setfacl -Rm user:apache:rx /srv/git From 4e55c52a1512e301fb1e641da56bf51f7e18319f Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 13:04:21 +0000 Subject: [PATCH 18/23] Let's not forget to create the remotes folder even for development --- diff --git a/doc/development.rst b/doc/development.rst index bcc321e..3f5562a 100644 --- a/doc/development.rst +++ b/doc/development.rst @@ -46,7 +46,7 @@ Create the folder that will receive the different git repositories: :: - mkdir {repos,docs,forks,tickets,requests} + mkdir {repos,docs,forks,tickets,requests,remotes} Run the server: From 47de6200749347cceed1726bfe737d9c6d3cad27 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 13:05:16 +0000 Subject: [PATCH 19/23] Actually, apache is not allowed to write --- diff --git a/doc/Install.rst b/doc/Install.rst index 18767c4..6c65988 100644 --- a/doc/Install.rst +++ b/doc/Install.rst @@ -172,7 +172,7 @@ git repositories created and managed by gitolite. To give apache this permission (required to make git clone via http work), we use facl :: - setfacl -m user:apache:rwx --default + setfacl -m user:apache:rx --default setfacl -Rdm user:apache:rx /srv/git setfacl -Rm user:apache:rx /srv/git From 9e4ee8fd9128f6821045e09900ef43b9a45718fa Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 13:05:30 +0000 Subject: [PATCH 20/23] Adjust the table of content --- diff --git a/doc/index.rst b/doc/index.rst index 87e2d0e..5951943 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -25,10 +25,11 @@ Contents: .. toctree:: :maxdepth: 2 - development - contributing + overview deployment configuration + development + contributing contributors From 1cdc75c680fa643f5ad2e6da61b6723400ae8084 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 13:06:38 +0000 Subject: [PATCH 21/23] Drop the deployment file replaced by the better install sections --- diff --git a/doc/deployment.rst b/doc/deployment.rst deleted file mode 100644 index 506e517..0000000 --- a/doc/deployment.rst +++ /dev/null @@ -1,89 +0,0 @@ -Deployment -========== - -From sources ------------- - -Clone the source:: - - git clone http://git.fedorahosted.org/git/pagure.git - -Install the dependencies listed in the ``requirements.txt`` file. - - -Copy the configuration files:: - - cp pagure.cfg.sample pagure.cfg - -Adjust the configuration files (secret key, database URL, admin group...). -See :doc:`configuration` for detailed information about the configuration. - - -Create the database scheme:: - - PAGURE_CONFIG=/path/to/pagure.cfg python createdb.py - -Create the folder that will receive the different git repositories: - -:: - - mkdir {repos,docs,forks,tickets} - - -Set up the WSGI as described below. - - -From system-wide packages -------------------------- - -Start by install pagure:: - - yum install pagure - -Adjust the configuration files: ``/etc/pagure/pagure.cfg``. -See :doc:`configuration` for detailed information about the configuration. - -Find the file used to create the database:: - - rpm -ql pagure |grep createdb.py - -Create the database scheme:: - - PAGURE_CONFIG=/etc/pagure/pagure.cfg python path/to/createdb.py - -Set up the WSGI as described below. - - -Set-up WSGI ------------ - -Start by installing ``mod_wsgi``:: - - yum install mod_wsgi - - -Then configure apache:: - - sudo vim /etc/httd/conf.d/pagure.conf - -uncomment the content of the file and adjust as desired. - - -Then edit the file ``/usr/share/pagure/pagure.wsgi`` and -adjust as needed. - - -Then restart apache and you should be able to access the website on -http://localhost/pkgdb - - -.. note:: `Flask `_ provides also some documentation - on how to `deploy Flask application with WSGI and apache - `_. - - -For testing ------------ - -See :doc:`development` if you want to run pagure just to test it. - diff --git a/doc/index.rst b/doc/index.rst index 5951943..408f67b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -26,7 +26,9 @@ Contents: :maxdepth: 2 overview - deployment + install + install_milter + install_evs configuration development contributing From 18e5d3c5969f319e934bb26eedcf7865e77fd314 Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 14:07:27 +0000 Subject: [PATCH 22/23] 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. From 2edf48a60d82c148e7ab649a01f7dde8fcb5cfae Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Jul 28 2015 14:15:38 +0000 Subject: [PATCH 23/23] Couple more adjustments to the documentation based on the feedback in the review --- diff --git a/doc/Install_milter.rst b/doc/Install_milter.rst index 1578ef5..fbb8a85 100644 --- a/doc/Install_milter.rst +++ b/doc/Install_milter.rst @@ -2,11 +2,12 @@ Installing pagure's milter ========================== 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 --------------------- diff --git a/doc/index.rst b/doc/index.rst index 3d18135..c31e15a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -10,9 +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. +* Open data: 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 + changed locally. * ``Freedom``: Pagure is fully Free and Open-Source Software!