README.rst 8.4 KB

  1. Pagure
  2. ======
  3. :Author: Pierre-Yves Chibon <>
  4. Pagure is a git-centered forge, python based using pygit2.
  5. With pagure you can host your project with its documentation, let your users
  6. report issues or request enhancements using the ticketing system and build your
  7. community of contributors by allowing them to fork your projects and contribute
  8. to it via the now-popular pull-request mechanism.
  9. Homepage:
  10. See it at work:
  11. Playground version:
  12. If you have any questions or just would like to discuss about pagure,
  13. feel free to drop by on IRC in the channel ``#pagure`` of the freenode server
  14. About its name
  15. ==============
  16. The name Pagure is taken from the French word 'pagure'. Pagure in French is used as the
  17. common name for the crustaceans from the `Paguroidea <>`_
  18. superfamily, which is basically the family of the Hermit crabs.
  19. Originating from French it is pronounced with a strong 'g' as you can hear
  20. on `this recording <>`_.
  21. Get it running
  22. ==============
  23. There are several options when it comes to a development environment.
  24. They are: Docker Compose, Vagrant, and manual. Choose an option below.
  25. Docker Compose
  26. ^^^^^^^^^^^^^^
  27. Docker Compose will provide you with a container which you can develop on.
  28. Install it `with these instructions <>`_.
  29. For more information about docker-compose cli, see:
  30. Once installed, create the folder that will receive the projects, forks, docs,
  31. requests and tickets' git repo. Run this command exactly as it appears::
  32. $ mkdir -p lcl/{repos,remotes,attachments,releases}
  33. A docker compose environment is available to run pagure. First use the following
  34. command to build the containers. ::
  35. $ docker-compose -f dev/docker-compose.yml build
  36. Once all the containers are built, run the following command to start the containers. ::
  37. $ docker-compose -f dev/docker-compose.yml up
  38. Once all the containers have started, you can access pagure on http://localhost:5000.
  39. To stop the containers, press Ctrl+C.
  40. To populate the container with test data and create a new account, run ::
  41. $ docker-compose -f dev/docker-compose.yml exec web python --all
  42. You can then login with any of the created users, by example:
  43. - username: pingou
  44. - password: testing123
  45. Vagrant
  46. ^^^^^^^
  47. For a more thorough introduction to Vagrant, see
  49. An example Vagrantfile is provided as ``Vagrantfile.example``. To use it,
  50. just copy it and install Vagrant. Instructions for Fedora::
  51. $ cp dev/Vagrantfile.example Vagrantfile
  52. $ sudo dnf install ansible libvirt vagrant-libvirt vagrant-sshfs vagrant-hostmanager
  53. $ vagrant up
  54. On Ubuntu, install Vagrant directly `from the website <>`_
  55. then run these commands instead::
  56. $ cp dev/Vagrantfile.example Vagrantfile
  57. $ sudo add-apt-repository ppa:ansible/ansible
  58. $ sudo apt update
  59. $ sudo apt install ansible libvirt0 openssh-server qemu libvirt-bin ebtables dnsmasq libxslt-dev libxml2-dev libvirt-dev zlib1g-dev ruby-dev
  60. $ vagrant plugin install vagrant-libvirt vagrant-sshfs vagrant-hostmanager
  61. If you get this error ``Block in synced_folders: Internal error. Invalid: sshfs``,
  62. when you run ``vagrant up`` , you need to install vagrant sshfs plugin, which can be done by::
  63. $ vagrant plugin install vagrant--sshfs
  64. and then::
  65. $ vagrant up
  66. The default ``Vagrantfile`` forwards ports from the host to the guest,
  67. so you can interact with the application as if it were running on your
  68. host machine.
  69. .. note::
  70. ``vagrant-hostmanager`` will automatically maintain /etc/hosts for you so you
  71. can access the development environment from the host using its hostname, which
  72. by default is ````. You can choose not to use this
  73. functionality by simply not installing the ``vagrant-hostmanager`` plugin, but
  74. if you want Pagure to provide valid URLs in the UI for git repositories, you
  75. will need to adjust Pagure's configuration found in ~/pagure.cfg on the guest.
  76. When the vagrant VM is up and running, connect to it with::
  77. $ vagrant ssh
  78. This will log you into the VM as the user ``vagrant`` which has a couple of aliases
  79. preconfigured::
  80. $ pstart # Starts pagure, the workers and other tasks
  81. $ pstop # Stops all those tasks again
  82. $ pstatus # Shows pagure status
  83. The Vagrant pagure doesn't have its own log file, use ``journalctl -f`` to
  84. show the pagure output. The verbosity can be configured in the pagure config file
  85. with the ``LOGGING`` parameter.
  86. Running the unit-tests
  87. **********************
  88. To run the unit-tests, there is container available with all the dependencies needed.
  89. First you will need to have podman installed on your workstation. ::
  90. $ sudo dnf install podman
  91. Use the following command to run the tests ::
  92. $ ./dev/
  93. This command will build a fedora based container and execute the test suite.
  94. If you wish to execute the test suite on a centos based container run the following command ::
  95. $ ./dev/ --centos
  96. When the test container image has been built you can skip the building step to save time
  97. and run directly the test suite. ::
  98. $ ./dev/ --skip-build
  99. $ ./dev/ --centos --skip-build
  100. You can also run a single test case ::
  101. $ ./dev/ tests/
  102. Or a single test ::
  103. $ ./dev/ tests/
  104. You can also get `run-tests-container` help ::
  105. $ ./dev/ --help
  106. Manually
  107. ^^^^^^^^
  108. * Install the needed system libraries::
  109. sudo dnf install git python3 python3-devel libgit2-devel redis \
  110. libjpeg-devel gcc libffi-devel redhat-rpm-config
  111. .. note:: Do note the version of libgit2 that you install, for example
  112. in ``libgit2-0.23.4-1`` you need to keep in mind the ``0.23``
  113. .. note:: On RHEL and derivative (CentOS, Scientific Linux) there is no
  114. `python3` package. Just `python36` or `python34` available in
  115. EPEL 7 (EPEL 6 only has `python34`). Choose the one you prefer
  116. (3.6 is newer and generally a better choice).
  117. * Retrieve the sources::
  118. git clone
  119. cd pagure
  120. * Install dependencies
  121. * create the virtual environment (use `pytohn3.X` explicitly on EPEL)::
  122. python3 -m venv pagure_env
  123. source ./pagure_env/bin/activate
  124. * Install the correct version of pygit2::
  125. pip install pygit2==<version of libgit2 found>.*
  126. So in our example::
  127. pip install pygit2==0.23.*
  128. * Install the rest of the dependencies::
  129. pip install -r requirements.txt
  130. * Create the folder that will receive the projects, forks, docs, requests and
  131. tickets' git repo::
  132. mkdir -p lcl/{repos,remotes,attachments,releases}
  133. * Copy and edit the alembic.ini file (especially the ``script_location`` key)::
  134. cp files/alembic.ini .
  135. vim alembic.ini
  136. * Set the ``script_location`` to ``alembic``, ie: the folder where the revisions
  137. are stored, relative to the location of the ``alembic.ini`` file.
  138. * Create the inital database scheme::
  139. python --initial alembic.ini
  140. * Enable and start redis server::
  141. sudo systemctl enable redis
  142. sudo systemctl start redis
  143. * Start a worker, in one terminal::
  144. ./
  145. * Run the application, in another terminal::
  146. ./
  147. * To get some profiling information you can also run it as::
  148. ./ --profile
  149. This will launch the application at
  150. * To run unit-tests on pagure
  151. * Install the dependencies::
  152. pip install -r requirements-testing.txt
  153. * Run it::
  154. python run
  155. You may use::
  156. python --help
  157. to check other options supported or read the source code ;-)
  158. .. note:: While testing for worker tasks, pagure uses celery in /usr/bin/
  159. Celery then looks for eventlet (which we use for testing only) at
  160. system level and not in virtual environment. You will need to
  161. install eventlet outside of your virtual environment if you are
  162. using one.