Blame README.rst

Pierre-Yves Chibon fe5017
Pagure
Pierre-Yves Chibon 2088eb
======
Pierre-Yves Chibon 2088eb
Pierre-Yves Chibon 306158
:Author:  Pierre-Yves Chibon <pingou@pingoured.fr></pingou@pingoured.fr>
Pierre-Yves Chibon 2088eb
Pierre-Yves Chibon 2088eb
Pierre-Yves Chibon 306158
Pagure is a git-centered forge, python based using pygit2.
Pierre-Yves Chibon 78e123
Pierre-Yves Chibon 306158
With pagure you can host your project with its documentation, let your users
Pierre-Yves Chibon 306158
report issues or request enhancements using the ticketing system and build your
Pierre-Yves Chibon 306158
community of contributors by allowing them to fork your projects and contribute
Pierre-Yves Chibon 306158
to it via the now-popular pull-request mechanism.
Pierre-Yves Chibon 2088eb
Pierre-Yves Chibon 2088eb
Rahul Bajaj 29b73b
Homepage: https://pagure.io/pagure
Stanislav Ochotnicky 6739d2
Pierre-Yves Chibon 4951c5
See it at work: https://pagure.io
Pierre-Yves Chibon 4951c5
Pierre-Yves Chibon 306158
Pierre-Yves Chibon 4951c5
Playground version: https://stg.pagure.io
Pierre-Yves Chibon 4951c5
Vivek Anand 72e0f0
If you have any questions or just would like to discuss about pagure,
Vivek Anand 72e0f0
feel free to drop by on IRC in the channel ``#pagure`` of the freenode server
Pierre-Yves Chibon 22c46f
Pierre-Yves Chibon bfbc7c
Pierre-Yves Chibon 64ca8d
About its name
Pierre-Yves Chibon 64ca8d
==============
Pierre-Yves Chibon 64ca8d
Pierre-Yves Chibon 64ca8d
The name Pagure is taken from the French word 'pagure'. Pagure in French is used as the
Pierre-Yves Chibon 64ca8d
common name for the crustaceans from the `Paguroidea <https: en.wikipedia.org="" hermit_crab="" wiki="">`_</https:>
Pierre-Yves Chibon 64ca8d
superfamily, which is basically the family of the Hermit crabs.
Pierre-Yves Chibon 64ca8d
Pierre-Yves Chibon 64ca8d
Originating from French it is pronounced with a strong 'g' as you can hear
Pierre-Yves Chibon 64ca8d
on `this recording <https: f="" how-do-you-pronounce-pagure="" master="" pagure.io="" pingou.ogg="" raw="">`_.</https:>
Pierre-Yves Chibon 64ca8d
Pierre-Yves Chibon 64ca8d
Pierre-Yves Chibon 2088eb
Get it running
Pierre-Yves Chibon 2088eb
==============
Pierre-Yves Chibon 2088eb
Jeremy Cline 4e3668
There are several options when it comes to a development environment. Vagrant
Jeremy Cline 4e3668
will provide you with a virtual machine which you can develop on, or you can
Jeremy Cline 4e3668
install it directly on your host machine.
Jeremy Cline 4e3668
Jeremy Cline 4e3668
Vagrant
Jeremy Cline 4e3668
^^^^^^^
Jeremy Cline 4e3668
Jeremy Cline 4e3668
For a more thorough introduction to Vagrant, see
Jeremy Cline 4e3668
https://fedoraproject.org/wiki/Vagrant.
Jeremy Cline 4e3668
Jeremy Cline 4e3668
An example Vagrantfile is provided as ``Vagrantfile.example``. To use it,
Jeremy Cline 4e3668
just copy it and install Vagrant::
Jeremy Cline 4e3668
Pierre-Yves Chibon dedefc
    $ cp dev/Vagrantfile.example Vagrantfile
Jeremy Cline 4e3668
    $ sudo dnf install ansible libvirt vagrant-libvirt vagrant-sshfs vagrant-hostmanager
Jeremy Cline 4e3668
    $ vagrant up
Jeremy Cline 4e3668
ymdatta f3827b
If you get this error ``Block in synced_folders: Internal error. Invalid: sshfs``,
ymdatta f3827b
when you run ``vagrant up`` , you need to install vagrant sshfs plugin, which can be done by::
ymdatta f3827b
ymdatta f3827b
    $ vagrant plugin install vagrant--sshfs
Pierre-Yves Chibon 64ca8d
ymdatta f3827b
and then::
ymdatta f3827b
ymdatta f3827b
    $ vagrant up
ymdatta f3827b
Jeremy Cline 4e3668
The default ``Vagrantfile`` forwards ports from the host to the guest,
Jeremy Cline 4e3668
so you can interact with the application as if it were running on your
Jeremy Cline 4e3668
host machine.
Jeremy Cline 4e3668
Jeremy Cline 4e3668
.. note::
Jeremy Cline 4e3668
    ``vagrant-hostmanager`` will automatically maintain /etc/hosts for you so you
Jeremy Cline 4e3668
    can access the development environment from the host using its hostname, which
Jeremy Cline 4e3668
    by default is ``pagure-dev.example.com``. You can choose not to use this
Jeremy Cline 4e3668
    functionality by simply not installing the ``vagrant-hostmanager`` plugin, but
Jeremy Cline 4e3668
    if you want Pagure to provide valid URLs in the UI for git repositories, you
Jeremy Cline 4e3668
    will need to adjust Pagure's configuration found in ~/pagure.cfg on the guest.
Jeremy Cline 4e3668
Clement Verna c4390f
Docker Compose
Clement Verna c4390f
^^^^^^^^^^^^^^
Farhaan Bukhsh a2549f
Create the folder that will receive the projects, forks, docs, requests and
Farhaan Bukhsh a2549f
tickets' git repo::
Farhaan Bukhsh a2549f
Farhaan Bukhsh a2549f
    mkdir -p lcl/{repos,remotes,attachments,releases}
Clement Verna c4390f
Clement Verna c4390f
A docker compose environment is available to run pagure. First use the following
Clement Verna c4390f
command to build the containers. ::
Clement Verna c4390f
Clement Verna c4390f
    $ docker-compose -f dev/docker-compose.yml build
Clement Verna c4390f
Clement Verna c4390f
Once all the containers are built, run the following command to start the containers. ::
Clement Verna c4390f
Clement Verna c4390f
    $ docker-compose -f dev/docker-compose.yml up -d
Clement Verna c4390f
Clement Verna c4390f
Once all the containers have started, you can access pagure on http://localhost:5000
Clement Verna c4390f
Clement Verna c4390f
To stop the containers, run the following ::
Clement Verna c4390f
Clement Verna c4390f
    $ docker-compose -f dev/docker-compose.yml stop
Clement Verna c4390f
Clement Verna c4390f
More information about docker-compose cli see https://docs.docker.com/compose/reference/.
Jeremy Cline 4e3668
Clement Verna 10c67d
Running the unit-tests
Clement Verna 10c67d
**********************
Clement Verna 50aeb2
Clement Verna 50aeb2
To run the unit-tests, there is container available with all the dependencies needed.
Clement Verna 50aeb2
Clement Verna d6ad1e
Use the following command to run the tests ::
Clement Verna 50aeb2
Clement Verna d6ad1e
    $ ./dev/run-tests-docker.py
Clement Verna 50aeb2
Clement Verna d6ad1e
This command will build a fedora based container and execute the test suite.
Clement Verna 50aeb2
Clement Verna d6ad1e
If you wish to execute the test suite on a centos based container run the following command ::
Clement Verna 50aeb2
Clement Verna d6ad1e
    $ ./dev/run-tests-docker.py --centos
Clement Verna 10c67d
Clement Verna d6ad1e
When the test container image has been built you can skip the building step to save time
Clement Verna d6ad1e
and run directly the test suite. ::
Clement Verna 10c67d
Clement Verna d6ad1e
    $ ./dev/run-tests-docker.py --skip-build
Clement Verna d6ad1e
    $ ./dev/run-tests-docker.py --centos --skip-build
Clement Verna d6ad1e
Clement Verna d6ad1e
You can also run a single test case ::
Clement Verna d6ad1e
Clement Verna d6ad1e
    $ ./dev/run-tests-docker.py tests/test_pagure_flask_ui_priorities.py
Clement Verna d6ad1e
Clement Verna d6ad1e
Or a single test ::
Clement Verna d6ad1e
Clement Verna d6ad1e
    $ ./dev/run-tests-docker.py tests/test_pagure_flask_ui_priorities.py:PagureFlaskPrioritiestests.test_ticket_with_no_priority
Clement Verna d6ad1e
Clement Verna d6ad1e
You can also get `run-tests-docker` help ::
Clement Verna d6ad1e
Clement Verna d6ad1e
    $ ./dev/run-tests-docker.py --help
Clement Verna 50aeb2
Jeremy Cline 4e3668
Manually
Jeremy Cline 4e3668
^^^^^^^^
Jeremy Cline 4e3668
Pierre-Yves Chibon 5dc04a
* Install the needed system libraries::
Pierre-Yves Chibon 306158
Miro Hrončok 4a5f28
    sudo dnf install git python3 libgit2-devel redis \
Pierre-Yves Chibon 306158
                     libjpeg-devel gcc libffi-devel redhat-rpm-config
Pierre-Yves Chibon 306158
Pierre-Yves Chibon a4a4c1
  .. note:: Do note the version of libgit2 that you install, for example
Pierre-Yves Chibon a4a4c1
            in ``libgit2-0.23.4-1`` you need to keep in mind the ``0.23``
Pierre-Yves Chibon 306158
Miro Hrončok 4a5f28
  .. note:: On RHEL and derivative (CentOS, Scientific Linux) there is no
Miro Hrončok 4a5f28
            `python3` package. Just `python36` or `python34` available in
Miro Hrončok 4a5f28
            EPEL 7 (EPEL 6 only has `python34`). Choose the one you prefer
Miro Hrončok 4a5f28
            (3.6 is newer and generally a better choice).
alunux 835397
Pierre-Yves Chibon 2088eb
* Retrieve the sources::
Pierre-Yves Chibon 2088eb
Rahul Bajaj 29b73b
    git clone https://pagure.io/pagure.git
Daniel Mach d27126
    cd pagure
Daniel Mach d27126
Daniel Mach d27126
* Install dependencies
Daniel Mach d27126
Miro Hrončok 4a5f28
  * create the virtual environment (use `pytohn3.X` explicitly on EPEL)::
Daniel Mach d27126
Miro Hrončok 4a5f28
      python3 -m venv pagure_env
Pierre-Yves Chibon 306158
      source ./pagure_env/bin/activate
Daniel Mach d27126
Pierre-Yves Chibon 306158
  * Install the correct version of pygit2::
Daniel Mach d27126
Pierre-Yves Chibon 306158
      pip install pygit2==<version found="" libgit2="" of="">.*</version>
Pierre-Yves Chibon 2088eb
Pierre-Yves Chibon 306158
    So in our example::
Pierre-Yves Chibon 2088eb
Pierre-Yves Chibon 306158
      pip install pygit2==0.23.*
Pierre-Yves Chibon 2088eb
Pierre-Yves Chibon 306158
  * Install the rest of the dependencies::
Pierre-Yves Chibon 2088eb
Pierre-Yves Chibon 306158
      pip install -r requirements.txt
Pierre-Yves Chibon 2088eb
Sayan Chowdhury 367479
Pierre-Yves Chibon 306158
* Create the folder that will receive the projects, forks, docs, requests and
Pierre-Yves Chibon 306158
  tickets' git repo::
Pierre-Yves Chibon 306158
Slavek Kabrda adea20
    mkdir -p lcl/{repos,remotes,attachments,releases}
Pierre-Yves Chibon 306158
Pierre-Yves Chibon 3335c0
* Copy and edit the alembic.ini file (especially the ``script_location`` key)::
Pierre-Yves Chibon 3335c0
Pierre-Yves Chibon 3335c0
    cp files/alembic.ini .
Pierre-Yves Chibon 3335c0
    vim alembic.ini
Pierre-Yves Chibon 3335c0
Pierre-Yves Chibon 5d2da2
* Set the ``script_location`` to ``alembic``, ie: the folder where the revisions
Pierre-Yves Chibon 5d2da2
  are stored, relative to the location of the ``alembic.ini`` file.
Pierre-Yves Chibon 306158
Pierre-Yves Chibon 306158
* Create the inital database scheme::
Daniel Mach d27126
Pierre-Yves Chibon 3335c0
    python createdb.py --initial alembic.ini
Sayan Chowdhury 367479
Karsten Hopp e70fba
* Enable and start redis server::
Karsten Hopp e70fba
Karsten Hopp e70fba
    systemctl enable redis
Karsten Hopp e70fba
    systemctl start redis
Karsten Hopp e70fba
Pierre-Yves Chibon ef25df
* Start a worker, in one terminal::
Sayan Chowdhury 367479
Pierre-Yves Chibon ef25df
    ./runworker.py
Pierre-Yves Chibon ef25df
Pierre-Yves Chibon ef25df
* Run the application, in another terminal::
Pierre-Yves Chibon 2088eb
Pierre-Yves Chibon 40cf0a
    ./runserver.py
Pierre-Yves Chibon 2088eb
Pierre-Yves Chibon 2088eb
Pierre-Yves Chibon b42030
* To get some profiling information you can also run it as::
Pierre-Yves Chibon b42030
Daniel Mach d27126
    ./runserver.py --profile
Pierre-Yves Chibon b42030
Pierre-Yves Chibon b42030
Pierre-Yves Chibon d0bf8c
This will launch the application at http://127.0.0.1:5000
rahul Bajaj c9695a
rahul Bajaj c9695a
rahul Bajaj c9695a
* To run unit-tests on pagure
rahul Bajaj c9695a
rahul Bajaj c9695a
  * Install the dependencies::
rahul Bajaj c9695a
rahul Bajaj c9695a
      pip install -r tests_requirements.txt
rahul Bajaj c9695a
rahul Bajaj c9695a
  * Run it::
rahul Bajaj c9695a
rahul Bajaj c9695a
      ./runtests.sh
Vivek Anand 6a3d0f
Vivek Anand 6a3d0f
    .. note:: While testing for worker tasks, pagure uses celery in /usr/bin/
Vivek Anand 6a3d0f
            Celery then looks for eventlet (which we use for testing only) at
Miro Hrončok 4a5f28
            system level and not in virtual environment. You will need to
Miro Hrončok 4a5f28
            install eventlet outside of your virtual environment if you are
Miro Hrončok 4a5f28
            using one.