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
René Genz 520020
* via the RPM package (recommended if you are using a RPM-based GNU/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 674992
    dnf install pagure pagure-milters pagure-ev pagure-webhook
Pierre-Yves Chibon 4751de
Pierre-Yves Chibon 4751de
or
Pierre-Yves Chibon 84fcb4
Pierre-Yves Chibon 4751de
::
Pierre-Yves Chibon b6a8b2
Pierre-Yves Chibon 674992
    yum install pagure pagure-milters pagure-ev pagure-webhook
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 674992
The ``pagure-webhook`` package contains the web-hook server.
Pierre-Yves Chibon 674992
Pierre-Yves Chibon 674992
Pierre-Yves Chibon b6a8b2
.. note:: The last three packages are optional, pagure would work fine without
Pierre-Yves Chibon 7d3eae
        them but the live-update, the webhook and the comment by email
Pierre-Yves Chibon 7d3eae
        services will not work.
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
bill auger 2f20e3
Pagure includes in its sources a ``setup.py`` automating 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 b6a8b2
.. 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 735175
    mkdir /srv/git/repositories/{docs,forks,tickets,requests,remotes}
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
bill auger 2f20e3
If not installed by RPM, the example file 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
bill auger 2f20e3
If you installed by RPM, you will find example WSGI files at:
bill auger 2f20e3
``/usr/share/pagure/pagure.wsgi`` for the core server 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.
Pierre-Yves Chibon 4e541d
Pierre-Yves Chibon 4e541d
* Create the database
Pierre-Yves Chibon 4e541d
Pierre-Yves Chibon 4e541d
You first need to create the database itself. For this, since pagure can
Pierre-Yves Chibon 4e541d
work with: `PostgreSQL <http: www.postgresql.org="">`_,</http:>
Pierre-Yves Chibon 4e541d
`MySQL <http: www.mysql.com="">`_ or `MariaDB <http: mariadb.org="">`_, we</http:></http:>
Pierre-Yves Chibon 4e541d
would like to invite you to consult the documentation of your database system
Pierre-Yves Chibon 4e541d
for this operation.
Pierre-Yves Chibon 4e541d
Pierre-Yves Chibon 4e541d
Once you have specified in the configuration file the to url used to connect
Pierre-Yves Chibon 4e541d
to the database, and create the database itself, you can now create the
Pierre-Yves Chibon 4e541d
tables, the database scheme.
Pierre-Yves Chibon 4e541d
Pierre-Yves Chibon f21396
For changes to existing tables, we rely on `Alembic <http: alembic.readthedocs.org="">`_.</http:>
Pierre-Yves Chibon f21396
It uses `revisions` to perform the upgrades, but to know which upgrades are
Pierre-Yves Chibon f21396
needed and which are already done, the current revision needs to be saved
Pierre-Yves Chibon 525e44
in the database. This will allow alembic to know and apply the new revision
Pierre-Yves Chibon 525e44
when running it.
Pierre-Yves Chibon f21396
Pierre-Yves Chibon f21396
In the ``alembic.ini`` file, one of the configuration key is most important:
Pierre-Yves Chibon f21396
``script_location`` which is the path to the ``versions`` folder containing
Pierre-Yves Chibon f21396
all the alembic migration files. The ``sqlalchemy.url`` configuration key if
Pierre-Yves Chibon f21396
missing will be replaced by the url filled in the configuration file of
Pierre-Yves Chibon f21396
pagure.
Pierre-Yves Chibon f21396
Pierre-Yves Chibon 4e541d
To create the database tables, you need to run the script
bill auger 2f20e3
``/usr/share/pagure/pagure_createdb.py`` and specify the configuration
Pierre-Yves Chibon f92b8c
to use for pagure and for alembic.
Pierre-Yves Chibon 4e541d
Pierre-Yves Chibon 4e541d
For example:
Pierre-Yves Chibon 4e541d
::
Pierre-Yves Chibon 4e541d
Pierre-Yves Chibon f92b8c
    python /usr/share/pagure/pagure_createdb.py -c /etc/pagure/pagure.cfg -i /etc/pagure/alembic.ini
Pierre-Yves Chibon 4e541d
Pierre-Yves Chibon 4e541d
This will tell ``/usr/share/pagure/pagure_createdb.py`` to use the database
Pierre-Yves Chibon f92b8c
information specified in the file ``/etc/pagure/pagure.cfg`` and to stamp
Pierre-Yves Chibon f92b8c
the database at the last alembic revision.
Pierre-Yves Chibon facfaf
Pierre-Yves Chibon 4ffa5f
.. warning:: Pagure's default configuration is using sqlite. This is fine
Pierre-Yves Chibon 4ffa5f
        for development purpose but not for production use as sqlite does
Pierre-Yves Chibon 4ffa5f
        not support all the operations needed when updating the database
Pierre-Yves Chibon 4ffa5f
        schema. Do use PostgreSQL, MySQL or MariaDB in production.
Pierre-Yves Chibon 4ffa5f
Pierre-Yves Chibon facfaf
For changes to existing tables, we rely on `Alembic <http: alembic.readthedocs.org="">`_.</http:>
Pierre-Yves Chibon facfaf
It uses `revisions` to perform the upgrades, but to know which upgrades are
Pierre-Yves Chibon facfaf
needed and which are already done, the current revision needs to be saved
Pierre-Yves Chibon facfaf
in the database. This will allow alembic to know apply the new revision when
Pierre-Yves Chibon facfaf
running it.
Pierre-Yves Chibon facfaf
Pierre-Yves Chibon f92b8c
In the ``alembic.ini`` file, one of the configuration key is most important:
Pierre-Yves Chibon f92b8c
``script_location`` which is the path to the ``versions`` folder containing
Pierre-Yves Chibon f92b8c
all the alembic migration files. The ``sqlalchemy.url`` configuration key if
Pierre-Yves Chibon f92b8c
missing will be replaced by the url filled in the configuration file of
Pierre-Yves Chibon f92b8c
pagure.
Pierre-Yves Chibon facfaf
Pierre-Yves Chibon f21396
.. warning:: Calling ``pagure_createdb.py`` is asked regularly in the
Pierre-Yves Chibon f21396
        UPGRADING.rst documentation, especially to handle database schema
Pierre-Yves Chibon f21396
        changes upon upgrades, but the ``--initial`` argument should only
Pierre-Yves Chibon f21396
        be used the first time as it will otherwise break upgrading the
Pierre-Yves Chibon f21396
        database schema via alembic.
Patrick Uiterwijk 78afb3
Pierre-Yves Chibon 525e44
.. note:: When install from source the script is called ``createdb.py`` and
Pierre-Yves Chibon 525e44
        not ``pagure_createdb.py``.
Pierre-Yves Chibon 525e44
Patrick Uiterwijk 78afb3
René Genz 520020
Set up virus scanning
René Genz 5d0807
---------------------
Patrick Uiterwijk 78afb3
Pagure can automatically scan uploaded attachments for viruses using Clam.
Patrick Uiterwijk 78afb3
To set this up, first install clamav-data-empty, clamav-server,
Patrick Uiterwijk 78afb3
clamav-server-systemd and clamav-update.
Patrick Uiterwijk 78afb3
Patrick Uiterwijk 78afb3
Then edit /etc/freshclam.conf, removing the Example line and run freshclam once
Patrick Uiterwijk 78afb3
to get an up to date database.
Patrick Uiterwijk 78afb3
Patrick Uiterwijk 78afb3
Copy /usr/share/doc/clamav-server/clamd.conf to /etc/clamd.conf and edit that
Patrick Uiterwijk 78afb3
too, again making sure to remove the Example line. Make sure to set LocalSocket
Patrick Uiterwijk 78afb3
to a file in a directory that exists, and set User to an existing system user.
Patrick Uiterwijk 78afb3
Patrick Uiterwijk 78afb3
Then start the clamd service and set VIRUS_SCAN_ATTACHMENTS = True in the
Patrick Uiterwijk 78afb3
Pagure configuration.