configuration.rst 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562
  1. Configuration
  2. =============
  3. Pagure offers a wide varieties of options that must or can be used to
  4. adjust its behavior.
  5. Must options
  6. ------------
  7. Here are the options you must set up in order to get pagure running.
  8. SECRET_KEY
  9. ~~~~~~~~~~
  10. This configuration key is used by flask to create the session. It should be kept secret
  11. and set as a long and random string.
  12. SALT_EMAIL
  13. ~~~~~~~~~~
  14. This configuration key is used to ensure that when sending
  15. notifications to different users, each one of them has a different, unique
  16. and un-fakable ``Reply-To`` header. This header is then used by the milter to find
  17. out if the response received is a real one or a fake/invalid one.
  18. DB_URL
  19. ~~~~~~
  20. This configuration key indicates to the framework how and where to connect to the database
  21. server. Pagure uses `SQLAchemy <http://www.sqlalchemy.org/>`_ to connect
  22. to a wide range of database server including MySQL, PostgreSQL, and SQLite.
  23. Examples values:
  24. ::
  25. DB_URL = 'mysql://user:pass@host/db_name'
  26. DB_URL = 'postgres://user:pass@host/db_name'
  27. DB_URL = 'sqlite:////var/tmp/pagure_dev.sqlite'
  28. Defaults to ``sqlite:////var/tmp/pagure_dev.sqlite``
  29. APP_URL
  30. ~~~~~~~
  31. This configuration key indicates the URL at which this pagure instance will be made available.
  32. Defaults to: ``https://pagure.org/``
  33. EMAIL_ERROR
  34. ~~~~~~~~~~~
  35. Pagure sends email when it catches an un-expected error (which saves you from
  36. having to monitor the logs regularly; but if you like, the error is still
  37. present in the logs).
  38. This configuration key allows you to specify to which email address to send
  39. these error reports.
  40. GIT_URL_SSH
  41. ~~~~~~~~~~~
  42. This configuration key provides the information to the user on how to clone
  43. the git repos hosted on pagure via `SSH <https://en.wikipedia.org/wiki/Secure_Shell>`_.
  44. The URL should end with a slash ``/``.
  45. Defaults to: ``'ssh://git@pagure.org/'``
  46. GIT_URL_GIT
  47. ~~~~~~~~~~~
  48. This configuration key provides the information to the user on how to clone
  49. the git repos hosted on pagure anonymously. This access can be granted via
  50. the ``git://`` or ``http(s)://`` protocols.
  51. The URL should end with a slash ``/``.
  52. Defaults to: ``'git://pagure.org/'``
  53. Repo Directories
  54. ----------------
  55. Each project in pagure has 4 git repositories:
  56. - the main repo for the code
  57. - the doc repo showed in the doc server
  58. - the ticket repo storing the metadata of the tickets
  59. - the request repo storing the metadata of the pull-requests
  60. There are then another 3 folders: one for specifying the locations of the forks, one
  61. for the remote git repo used for the remotes pull-requests (ie: those coming from
  62. a project not hosted on this instance of pagure), and one for user-uploaded tarballs.
  63. GIT_FOLDER
  64. ~~~~~~~~~~
  65. This configuration key points to the folder where the git repos for the
  66. source code of the projects are stored.
  67. DOCS_FOLDER
  68. ~~~~~~~~~~~
  69. This configuration key points to the folder where the git repos for the
  70. documentation of the projects are stored.
  71. TICKETS_FOLDER
  72. ~~~~~~~~~~~~~~
  73. This configuration key points to the folder where the git repos for the
  74. metadata of the tickets opened against the project are stored .
  75. REQUESTS_FOLDER
  76. ~~~~~~~~~~~~~~~
  77. This configuration key points to the folder where the git repos for the
  78. metadata of the pull-requests opened against the project are stored.
  79. REMOTE_GIT_FOLDER
  80. ~~~~~~~~~~~~~~~~~
  81. This configuration key points to the folder where the remote git repos (ie:
  82. not hosted on pagure) that someone used to open a pull-request against a
  83. project hosted on pagure are stored.
  84. UPLOAD_FOLDER_PATH
  85. ~~~~~~~~~~~~~~~~~~
  86. This configuration key points to the folder where user-uploaded tarballs
  87. are stored and served from.
  88. SESSION_COOKIE_SECURE
  89. ~~~~~~~~~~~~~~~~~~~~~
  90. When this is set to True, the session cookie will only be returned to the
  91. server via ssl (https). If you connect to the server via plain http, the
  92. cookie will not be sent. This prevents sniffing of the cookie contents.
  93. This may be set to False when testing your application but should always
  94. be set to True in production.
  95. Defaults to: ``False`` for development, must be ``True`` in production with
  96. https.
  97. FROM_EMAIL
  98. ~~~~~~~~~~
  99. This configuration key specifies the email address used by this pagure instance
  100. when sending emails (notifications).
  101. Defaults to: ``pagure@pagure.org``
  102. DOMAIN_EMAIL_NOTIFICATIONS
  103. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  104. This configuration key specifies the domain used by this pagure instance
  105. when sending emails (notifications). More precisely, it is used
  106. when building the ``msg-id`` header of the emails sent.
  107. Defaults to: ``pagure.org``
  108. VIRUS_SCAN_ATTACHMENTS
  109. ~~~~~~~~~~~~~~~~~~~~~~
  110. This configuration key configures whether attachments are scanned for viruses on
  111. upload. For more information, see the install.rst guide.
  112. Defaults to: ``False``
  113. Configure Gitolite
  114. ------------------
  115. Pagure uses `gitolite <http://gitolite.com/>`_ as an authorization layer.
  116. Gitolite relies on `SSH <https://en.wikipedia.org/wiki/Secure_Shell>`_ for
  117. the authentication. In other words, SSH lets you in and gitolite checks if you
  118. are allowed to do what you are trying to do once you are inside.
  119. GITOLITE_HOME
  120. ~~~~~~~~~~~~~
  121. This configuration key points to the home directory of the user under which
  122. gitolite is ran.
  123. GITOLITE_VERSION
  124. ~~~~~~~~~~~~~~~~
  125. This configuration key specifies which version of gitolite you are
  126. using, it can be either ``2`` or ``3``.
  127. Defaults to: ``3``.
  128. GITOLITE_KEYDIR
  129. ~~~~~~~~~~~~~~~
  130. This configuration key points to the folder where gitolite stores and accesses
  131. the public SSH keys of all the user have access to the server.
  132. Since pagure is the user interface, it is pagure that writes down the files
  133. in this directory, effectively setting up the users to be able to use gitolite.
  134. GITOLITE_CONFIG
  135. ~~~~~~~~~~~~~~~
  136. This configuration key points to the gitolite.conf file where pagure writes
  137. the gitolite repository access configuration.
  138. GL_RC
  139. ~~~~~
  140. This configuration key points to the file ``gitolite.rc`` used by gitolite
  141. to record who has access to what (ie: who has access to which repo/branch).
  142. GL_BINDIR
  143. ~~~~~~~~~
  144. This configuration key indicates the folder in which the gitolite tools can
  145. be found. It can be as simple as ``/usr/bin/`` if the tools have been installed
  146. using a package manager or something like ``/opt/bin/`` for a more custom
  147. install.
  148. EventSource options
  149. -------------------
  150. EVENTSOURCE_SOURCE
  151. ~~~~~~~~~~~~~~~~~~
  152. This configuration key indicates the URL at which the EventSource server is
  153. available. If not defined, pagure will behave as if there are no EventSource
  154. server running.
  155. EVENTSOURCE_PORT
  156. ~~~~~~~~~~~~~~~~
  157. This configuration key indicates the port at which the EventSource server is
  158. running.
  159. .. note:: The EventSource server requires a redis server (see ``Redis options``
  160. below)
  161. Web-hooks notifications
  162. -----------------------
  163. WEBHOOK
  164. ~~~~~~~
  165. This configuration key allows turning on or off web-hooks notifications for
  166. this pagure instance.
  167. Defaults to: ``False``.
  168. .. note:: The Web-hooks server requires a redis server (see ``Redis options``
  169. below)
  170. Redis options
  171. -------------
  172. REDIS_HOST
  173. ~~~~~~~~~~
  174. This configuration key indicates the host at which the `redis <http://redis.io/>`_
  175. server is running.
  176. Defaults to: ``0.0.0.0``.
  177. REDIS_PORT
  178. ~~~~~~~~~~
  179. This configuration key indicates the port at which the redis server can be
  180. contacted.
  181. Defaults to: ``6379``.
  182. REDIS_DB
  183. ~~~~~~~~
  184. This configuration key indicates the name of the redis database to use for
  185. communicating with the EventSource server.
  186. Defaults to: ``0``.
  187. Authentication options
  188. ----------------------
  189. ADMIN_GROUP
  190. ~~~~~~~~~~~
  191. List of groups, either local or remote (if the openid server used supports the
  192. group extension), that are the site admins. These admins can regenerate the
  193. gitolite configuration, the ssh key files, and the hook-token for every project
  194. as well as manage users and groups.
  195. PAGURE_ADMIN_USERS
  196. ~~~~~~~~~~~~~~~~~~
  197. List of local users that are the site admins. These admins have the same rights as
  198. the users in the admin groups listed above as well as admin rights to
  199. all projects hosted on this pagure instance.
  200. Optional options
  201. ----------------
  202. SSH_KEYS
  203. ~~~~~~~~
  204. It is a good pratice to publish the fingerprint and public SSH key of a
  205. server you provide access to.
  206. Pagure offers the possibility to expose this information based on the values
  207. set in the configuration file, in the ``SSH_KEYS`` configuration key.
  208. See the `SSH hostkeys/Fingerprints page on pagure.io <https://pagure.io/ssh_info>`_.
  209. .. warning: The format is important
  210. SSH_KEYS = {'RSA': {'fingerprint': '<foo>', 'pubkey': '<bar>'}}
  211. Where `<foo>` and `<bar>` must be replaced by your values.
  212. ITEM_PER_PAGE
  213. ~~~~~~~~~~~~~
  214. This configuration key allows you to configure the length of a page by
  215. setting the number of items on the page. Items can be commits, users, groups,
  216. or projects for example.
  217. Defaults to: ``50``.
  218. SMTP_SERVER
  219. ~~~~~~~~~~~
  220. This configuration key specifies the SMTP server to use when
  221. sending emails.
  222. Defaults to: ``localhost``.
  223. SMTP_PORT
  224. ~~~~~~~~~
  225. This configuration key specifies the SMTP server port.
  226. SMTP by default uses TCP port 25. The protocol for mail submission is
  227. the same, but uses port 587.
  228. SMTP connections secured by SSL, known as SMTPS, default to port 465
  229. (nonstandard, but sometimes used for legacy reasons).
  230. Defaults to: ``25``
  231. SMTP_SSL
  232. ~~~~~~~~
  233. This configuration key specifies whether the SMTP connections
  234. should be secured over SSL.
  235. Defaults to: ``False``
  236. SMTP_USERNAME
  237. ~~~~~~~~~~~~~
  238. This configuration key allows usage of SMTP with auth.
  239. Note: Specify SMTP_USERNAME and SMTP_PASSWORD for using SMTP auth
  240. Defaults to: ``None``
  241. SMTP_PASSWORD
  242. ~~~~~~~~~~~~~
  243. This configuration key allows usage of SMTP with auth.
  244. Note: Specify SMTP_USERNAME and SMTP_PASSWORD for using SMTP auth
  245. Defaults to: ``None``
  246. SHORT_LENGTH
  247. ~~~~~~~~~~~~
  248. This configuration key specifies the length of the commit ids or
  249. file hex displayed in the user interface.
  250. Defaults to: ``6``.
  251. BLACKLISTED_PROJECTS
  252. ~~~~~~~~~~~~~~~~~~~~
  253. This configuration key specifies a list of project names that are forbidden.
  254. This list is used for example to avoid conflicts at the URL level between the
  255. static files located under ``/static/`` and a project that would be named
  256. ``static`` and thus be located at ``/static``.
  257. Defaults to:
  258. ::
  259. [
  260. 'static', 'pv', 'releases', 'new', 'api', 'settings',
  261. 'logout', 'login', 'users', 'groups'
  262. ]
  263. CHECK_SESSION_IP
  264. ~~~~~~~~~~~~~~~~
  265. This configuration key specifies whether to check the user's IP
  266. address when retrieving its session. This makes things more secure but
  267. under certain setups it might not work (for example if there
  268. are proxies in front of the application).
  269. Defaults to: ``True``.
  270. PAGURE_AUTH
  271. ~~~~~~~~~~~~
  272. This configuration key specifies which authentication method to use.
  273. Pagure currently supports two authentication methods: one relying on the
  274. Fedora Account System `FAS <https://admin.fedoraproject.org/accounts>`_,
  275. and the other using only the local database.
  276. It can therefore be either ``fas`` or ``local``.
  277. Defaults to: ``fas``.
  278. IP_ALLOWED_INTERNAL
  279. ~~~~~~~~~~~~~~~~~~~
  280. This configuration key specifies which IP addresses are allowed
  281. to access the internal API endpoint. These endpoints are accessed by the
  282. milters for example and allow performing actions in the name of someone else
  283. which is sensitive, thus the origin of the request using
  284. these endpoints is validated.
  285. Defaults to: ``['127.0.0.1', 'localhost', '::1']``.
  286. MAX_CONTENT_LENGTH
  287. ~~~~~~~~~~~~~~~~~~
  288. This configuration key specifies the maximum file size allowed when
  289. uploading content to pagure (for example, screenshots to a ticket).
  290. Defaults to: ``4 * 1024 * 1024`` which corresponds to 4 megabytes.
  291. ENABLE_TICKETS
  292. ~~~~~~~~~~~~~~
  293. This configuration key activates or de-activates the ticketing system
  294. for all the projects hosted on this pagure instance.
  295. Defaults to: ``True``
  296. ENABLE_NEW_PROJECTS
  297. ~~~~~~~~~~~~~~~~~~~
  298. This configuration key permits or forbids creation of new projects via
  299. the user interface of this pagure instance.
  300. Defaults to: ``True``
  301. ENABLE_DEL_PROJECTS
  302. ~~~~~~~~~~~~~~~~~~~
  303. This configuration key permits or forbids deletiion of projects via
  304. the user interface of this pagure instance.
  305. Defaults to: ``True``
  306. EMAIL_SEND
  307. ~~~~~~~~~~
  308. This configuration key enables or disables all email notifications for
  309. this pagure instance. This can be useful to turn off when developing on
  310. pagure, or for test or pre-production instances.
  311. Defaults to: ``True``.
  312. .. note::
  313. This does not disable emails to the email address set in ``EMAIL_ERROR``.
  314. OLD_VIEW_COMMIT_ENABLED
  315. ~~~~~~~~~~~~~~~~~~~~~~~
  316. In version 1.3, pagure changed its URL scheme to view the commit of a
  317. project in order to add support for pseudo-namespaced projects.
  318. For pagure instances older than 1.3, who care about backward compatibility,
  319. we added an endpoint ``view_commit_old`` that brings URL backward
  320. compatibility for URLs using the complete git hash (the 40 characters).
  321. For URLs using a shorter hash, the URLs will remain broken.
  322. This configuration key enables or disables this backward compatibility
  323. which is useful for pagure instances running since before 1.3 but is not
  324. for newer instances.
  325. Defaults to: ``False``.
  326. PAGURE_CI_SERVICES
  327. ~~~~~~~~~~~~~~~~~~
  328. Pagure can be configure to integrate results of a Continuous Integration (CI)
  329. service to pull-requests open against a project.
  330. To enable this integration, follow the documentation on how to install
  331. pagure-ci and set this configuration key to ``['jenkins']`` (Jenkins being
  332. the only CI service supported at the moment).
  333. Defaults to: ``None``.
  334. .. warning:: Requires `Redis` to be configured and running.
  335. INSTANCE_NAME
  336. ~~~~~~~~~~~~~
  337. This allows giving a name to this running instance of pagure. The name is
  338. then used in the welcome screen showns upon first login.
  339. Defaults to: ``Pagure``
  340. .. note: the welcome screen currently does not work with the `local`
  341. authentication.