From 0eaaebd6f72a38c597e45984e5b8180752db9bcf Mon Sep 17 00:00:00 2001 From: Pierre-Yves Chibon Date: Aug 03 2015 09:03:25 +0000 Subject: Rename Install.rst to install.rst to match the other files --- diff --git a/doc/Install.rst b/doc/Install.rst deleted file mode 100644 index 4572f9d..0000000 --- a/doc/Install.rst +++ /dev/null @@ -1,193 +0,0 @@ -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 (a -mail filter to hook into a MTA). - -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. - -# 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 - - -* 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 -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 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 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 - - -* Give apache permission to read the repositories owned by the ``git`` user. - -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 file access control lists (aka FACL): -:: - setfacl -m user:apache:rx --default - 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. diff --git a/doc/install.rst b/doc/install.rst new file mode 100644 index 0000000..4572f9d --- /dev/null +++ b/doc/install.rst @@ -0,0 +1,193 @@ +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 (a +mail filter to hook into a MTA). + +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. + +# 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 + + +* 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 +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 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 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 + + +* Give apache permission to read the repositories owned by the ``git`` user. + +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 file access control lists (aka FACL): +:: + setfacl -m user:apache:rx --default + 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.