Blame doc/install.rst

Pierre-Yves Chibon 4751de
Installing pagure
Pierre-Yves Chibon 4751de
=================
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
There are two ways to install pagure:
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
* via the RPM package (recommanded if you are using a RPM-based linux distribution)
Pierre-Yves Chibon 4751de
* via the setup.py
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
Installing pagure via RPM
Pierre-Yves Chibon 4751de
-------------------------
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
Here as well there are two ways of obtaining the RPM:
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
* From the main repositories
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
Pagure is packaged for Fedora since Fedora 21 and is available for RHEL and
Pierre-Yves Chibon 18e5d3
its derivative via the `EPEL repository <https: epel="" fedoraproject.org="" wiki="">`.</https:>
Pierre-Yves Chibon 18e5d3
So installing it is as easy as:
Pierre-Yves Chibon 4751de
::
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
    dnf install pagure pagure-milters pagure-ev
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
or
Pierre-Yves Chibon 84fcb4
Pierre-Yves Chibon 4751de
::
Pierre-Yves Chibon 4751de
    yum install pagure pagure-milters pagure-ev
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
The ``pagure`` package contains the core of the application and the doc server.
Pierre-Yves Chibon 4751de
(See the ``Overview`` page for a global overview of the structure of the
Pierre-Yves Chibon 4751de
project).
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 18e5d3
The ``pagure-milters`` package contains, as the name says, the milter (a
Pierre-Yves Chibon 18e5d3
mail filter to hook into a MTA).
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
The ``pagure-ev`` package contains the eventsource server.
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 36036e
..note:: The last two packages are optional, pagure would work fine without
Pierre-Yves Chibon 4751de
        them.
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
* From the sources
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
If you wish to run a newer version of pagure than what is in the repositories
Pierre-Yves Chibon 4751de
you can easily rebuild it as RPM.
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
Simply follow these steps:
Pierre-Yves Chibon 4751de
# Clone the sources::
Pierre-Yves Chibon 36036e
Pierre-Yves Chibon 4751de
    git clone https://pagure.io/pagure.git
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
# Go to the folder::
Pierre-Yves Chibon 36036e
Pierre-Yves Chibon 4751de
    cd pagure
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
# Build a tarball of the latest version of pagure::
Pierre-Yves Chibon 36036e
Pierre-Yves Chibon 4751de
    python setup.py sdist
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
# Build the RPM::
Pierre-Yves Chibon 36036e
Pierre-Yves Chibon 4751de
    rpmbuild -ta dist/pagure*.tar.gz
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
This will build pagure from the version present in your clone.
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 18e5d3
Once, the RPM is installed the services ``pagure_milter`` and ``pagure_ev``
Pierre-Yves Chibon 4751de
are ready to be used but the database and the web-application parts still
Pierre-Yves Chibon 4751de
need to be configured.
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
Installing pagure via setup.py
Pierre-Yves Chibon 4751de
------------------------------
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
Pagure includes in its sources a ``setup.py`` automatint the installation
Pierre-Yves Chibon 4751de
of the web applications of pagure (ie: the core + the doc server).
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
To install pagure via this mechanism simply follow these steps:
Pierre-Yves Chibon 4751de
# Clone the sources::
Pierre-Yves Chibon 36036e
Pierre-Yves Chibon 4751de
    git clone https://pagure.io/pagure.git
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
# Go to the folder::
Pierre-Yves Chibon 36036e
Pierre-Yves Chibon 4751de
    cd pagure
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
# Install the latest version of pagure::
Pierre-Yves Chibon 36036e
Pierre-Yves Chibon 4751de
    python setup.py build
Pierre-Yves Chibon 4751de
    sudo python setup.py install
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 36036e
..note:: To install the eventsource server or the milter, refer to their
Pierre-Yves Chibon 4751de
        respective documentations.
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
# Install the additional files as follow:
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
+------------------------------+------------------------------------------+
Pierre-Yves Chibon c8389c
|         Source               |             Destination                  |
Pierre-Yves Chibon c8389c
+=============================+===========================================+
Pierre-Yves Chibon c8389c
| ``files/pagure.cfg.sample``  | ``/etc/pagure/pagure.cfg``               |
Pierre-Yves Chibon c8389c
+------------------------------+------------------------------------------+
Pierre-Yves Chibon c8389c
| ``files/alembic.ini``        | ``/etc/pagure/alembic.ini``              |
Pierre-Yves Chibon c8389c
+------------------------------+------------------------------------------+
Pierre-Yves Chibon c8389c
| ``files/pagure.conf``        | ``/etc/httpd/conf.d/pagure.conf``        |
Pierre-Yves Chibon c8389c
+------------------------------+------------------------------------------+
Pierre-Yves Chibon c8389c
| ``files/pagure.wsgi``        | ``/usr/share/pagure/pagure.wsgi``        |
Pierre-Yves Chibon c8389c
+------------------------------+------------------------------------------+
Pierre-Yves Chibon c8389c
| ``createdb.py``              | ``/usr/share/pagure/pagure_createdb.py`` |
Pierre-Yves Chibon c8389c
+------------------------------+------------------------------------------+
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
Set-up pagure
Pierre-Yves Chibon c8389c
-------------
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon 18e5d3
Once pagure's files are installed, you still need to set up some things.
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
* Create the folder release
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
This folder is used by project maintainers to upload the tarball of the
Pierre-Yves Chibon c8389c
releases of their project.
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
This folder must be accessible by the user under which the application is
Pierre-Yves Chibon c8389c
running (in our case: ``git``).
Pierre-Yves Chibon c8389c
::
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
    mkdir -p /var/www/releases
Pierre-Yves Chibon c8389c
    chown git:git /var/www/releases
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon 17b915
* Create the folders where the repos, forks and checkouts will be stored
Pierre-Yves Chibon 17b915
Pierre-Yves Chibon 17b915
Pagure stores the sources of a project in a git repo, offers a place to
Pierre-Yves Chibon 17b915
store the project's documentation in another repo, stores a JSON dump of all
Pierre-Yves Chibon 17b915
issues and of all pull-requests in another two repos, and keeps a local
Pierre-Yves Chibon 17b915
checkout of remote projects when asked to do remote pull-requests.
Pierre-Yves Chibon 17b915
All these repositories are stored in different folders that must be
Pierre-Yves Chibon 17b915
created manually.
Pierre-Yves Chibon 17b915
Pierre-Yves Chibon 17b915
For example you can place them under ``/srv/git/repositories/`` which would
Pierre-Yves Chibon 17b915
make ``/srv/git`` the home of your gitolite user.
Pierre-Yves Chibon 17b915
Pierre-Yves Chibon 17b915
You would then create the folders with:
Pierre-Yves Chibon 17b915
::
Pierre-Yves Chibon 36036e
Pierre-Yves Chibon 17b915
    mkdir /srv/git/repositories/{docs,forks,tickets,requests,checkouts}
Pierre-Yves Chibon 17b915
Pierre-Yves Chibon 17b915
Pierre-Yves Chibon c8389c
* Configure apache
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
If installed by RPM, you will find an example apache configuration file
Pierre-Yves Chibon c8389c
at: ``/etc/httpd/conf.d/pagure.conf``.
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
If not installed by RPM, the example files is present in the sources at:
Pierre-Yves Chibon c8389c
``files/pagure.conf``.
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
Adjust it for your needs.
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
* Configure the WSGI file
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon 18e5d3
If you installed by RPM, you will find an example WSGI file at:
Pierre-Yves Chibon c8389c
``/usr/share/pagure/pagure.wsgi`` and ``/usr/share/pagure/docs_pagure.wsgi``
Pierre-Yves Chibon c8389c
for the doc server.
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon 18e5d3
If you did not install by RPM, these files are present in the sources at:
Pierre-Yves Chibon c8389c
``files/pagure.wsgi`` and ``files/doc_pagure.wsgi``.
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
Adjust them for your needs
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
* Give apache permission to read the repositories owned by the ``git`` user.
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon 18e5d3
For the sake of this document, we assume that the web application runs under
Pierre-Yves Chibon 18e5d3
the ``git`` user, the same user as your gitolite user, but apache itself
Pierre-Yves Chibon 18e5d3
runs under the ``httpd`` (or ``apache2``) user. So by default, apache
Pierre-Yves Chibon 18e5d3
will not be allowed to read git repositories created and managed by gitolite.
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
To give apache this permission (required to make git clone via http work),
Pierre-Yves Chibon 18e5d3
we use file access control lists (aka FACL):
Pierre-Yves Chibon c8389c
::
Pierre-Yves Chibon 36036e
Pierre-Yves Chibon 47de62
    setfacl -m user:apache:rx --default
Pierre-Yves Chibon c8389c
    setfacl -Rdm user:apache:rx /srv/git
Pierre-Yves Chibon c8389c
    setfacl -Rm user:apache:rx /srv/git
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
Where ``/srv/git`` is the home of your gitolite user (which will thus need
Pierre-Yves Chibon c8389c
to be adjusted for your configuration).
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
* Set up the configuration file of pagure
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
This is an important step which concerns the file ``/etc/pagure/pagure.cfg``.
Pierre-Yves Chibon c8389c
If you have installed pagure by RPM, this file is already there, otherwise
Pierre-Yves Chibon c8389c
you can find an example one in the sources at: ``files/pagure.cfg.sample``
Pierre-Yves Chibon c8389c
that you will have to copy to the right location.
Pierre-Yves Chibon c8389c
Pierre-Yves Chibon c8389c
Confer the ``Configuration`` section of this documentation for a full
Pierre-Yves Chibon c8389c
explanation of all the options of pagure.