diff --git a/doc/configuration.rst b/doc/configuration.rst
index 60946a2..f0c1792 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -14,32 +14,32 @@ Here are the options you must set up in order to get pagure running.
SECRET_KEY
~~~~~~~~~~
-This key is used by flask to create the session. It should be kept secret
+This configuration key is used by flask to create the session. It should be kept secret
and set as a long and random string.
SALT_EMAIL
~~~~~~~~~~
-This key is used for when sending notification to ensure that when sending
+This configuration key is used to ensure that when sending
notifications to different users, each one of them has a different, unique
-and un-fakable ``Reply-To`` header that is then used by the milter to find
+and un-fakable ``Reply-To`` header. This header is then used by the milter to find
out if the response received is a real one or a fake/invalid one.
DB_URL
~~~~~~
-This key indicates to the framework how and where to connect to the database
-server. Pagure using `SQLAchemy `_ it can connect
-to a wide range of database server including MySQL, PostgreSQL and SQLite.
+This configuration key indicates to the framework how and where to connect to the database
+server. Pagure uses `SQLAchemy `_ to connect
+to a wide range of database server including MySQL, PostgreSQL, and SQLite.
Examples values:
::
- DB_URL=mysql://user:pass@host/db_name
- DB_URL=postgres://user:pass@host/db_name
+ DB_URL = 'mysql://user:pass@host/db_name'
+ DB_URL = 'postgres://user:pass@host/db_name'
DB_URL = 'sqlite:////var/tmp/pagure_dev.sqlite'
Defaults to ``sqlite:////var/tmp/pagure_dev.sqlite``
@@ -48,7 +48,7 @@ Defaults to ``sqlite:////var/tmp/pagure_dev.sqlite``
APP_URL
~~~~~~~
-This key indicates the URL at which this pagure instance will be made available.
+This configuration key indicates the URL at which this pagure instance will be made available.
Defaults to: ``https://pagure.org/``
@@ -56,11 +56,11 @@ Defaults to: ``https://pagure.org/``
EMAIL_ERROR
~~~~~~~~~~~
-Pagure sends email when it caches an un-expected error (which saves you from
-having to monitor the logs regularly but if you like, the error is still
+Pagure sends email when it catches an un-expected error (which saves you from
+having to monitor the logs regularly; but if you like, the error is still
present in the logs).
-This setting allows you to specify to which email address to send these error
-reports.
+This configuration key allows you to specify to which email address to send
+these error reports.
GIT_URL_SSH
@@ -85,29 +85,26 @@ The URL should end with a slash ``/``.
Defaults to: ``'git://pagure.org/'``
-GIT_FOLDER
-~~~~~~~~~~
-
-This configuration key points to where the folders containing the git repos
-of the projects are located.
+Repo Directories
+----------------
Each project in pagure has 4 git repositories:
- the main repo for the code
- the doc repo showed in the doc server
-- the ticket and request repos storing the metadata of the
- tickets/pull-requests
+- the ticket repo storing the metadata of the tickets
+- the request repo storing the metadata of the pull-requests
-There are then another 2 folders specifying the locations of the forks and
-remote git repo used for the remotes pull-requests (ie: pull-request coming
-from a project not hosted on this instance of pagure).
+There are then another 3 folders: one for specifying the locations of the forks, one
+for the remote git repo used for the remotes pull-requests (ie: those coming from
+a project not hosted on this instance of pagure), and one for user-uploaded tarballs.
-FORK_FOLDER
-~~~~~~~~~~~
+GIT_FOLDER
+~~~~~~~~~~
-This configuration key points to the folder where the git repos of forks of
-the projects are stored.
+This configuration key points to the folder where the git repos for the
+source code of the projects are stored.
DOCS_FOLDER
@@ -120,14 +117,14 @@ documentation of the projects are stored.
TICKETS_FOLDER
~~~~~~~~~~~~~~
-This configuration key points to the folder where the git repos storing the
+This configuration key points to the folder where the git repos for the
metadata of the tickets opened against the project are stored .
REQUESTS_FOLDER
~~~~~~~~~~~~~~~
-This configuration key points to the folder where the git repos storing the
+This configuration key points to the folder where the git repos for the
metadata of the pull-requests opened against the project are stored.
@@ -139,6 +136,13 @@ not hosted on pagure) that someone used to open a pull-request against a
project hosted on pagure are stored.
+UPLOAD_FOLDER_PATH
+~~~~~~~~~~~~~~~~~~
+
+This configuration key points to the folder where user-uploaded tarballs
+are stored and served from.
+
+
SESSION_COOKIE_SECURE
~~~~~~~~~~~~~~~~~~~~~
@@ -155,7 +159,7 @@ https.
FROM_EMAIL
~~~~~~~~~~
-This setting allows one to specify the email address used by this pagure instance
+This configuration key specifies the email address used by this pagure instance
when sending emails (notifications).
Defaults to: ``pagure@pagure.org``
@@ -164,8 +168,8 @@ Defaults to: ``pagure@pagure.org``
DOMAIN_EMAIL_NOTIFICATIONS
~~~~~~~~~~~~~~~~~~~~~~~~~~
-This setting allows one to specify the domain used by this pagure instance
-when sending emails (notifications). More precisely, this setting is used
+This configuration key specifies the domain used by this pagure instance
+when sending emails (notifications). More precisely, it is used
when building the ``msg-id`` header of the emails sent.
Defaults to: ``pagure.org``
@@ -174,7 +178,7 @@ Defaults to: ``pagure.org``
VIRUS_SCAN_ATTACHMENTS
~~~~~~~~~~~~~~~~~~~~~~
-This setting configures whether attachments are scanned for viruses on
+This configuration key configures whether attachments are scanned for viruses on
upload. For more information, see the install.rst guide.
Defaults to: ``False``
@@ -192,14 +196,14 @@ are allowed to do what you are trying to do once you are inside.
GITOLITE_HOME
~~~~~~~~~~~~~
-This configuration key should point to the home of the user under which
-gitolite is run.
+This configuration key points to the home directory of the user under which
+gitolite is ran.
GITOLITE_VERSION
~~~~~~~~~~~~~~~~
-This configuration key allows one to specify which version of gitolite you are
+This configuration key specifies which version of gitolite you are
using, it can be either ``2`` or ``3``.
Defaults to: ``3``.
@@ -212,13 +216,20 @@ This configuration key points to the folder where gitolite stores and accesses
the public SSH keys of all the user have access to the server.
Since pagure is the user interface, it is pagure that writes down the files
-in this directory effectively setting up the users to be able to use gitolite.
+in this directory, effectively setting up the users to be able to use gitolite.
+
+
+GITOLITE_CONFIG
+~~~~~~~~~~~~~~~
+
+This configuration key points to the gitolite.conf file where pagure writes
+the gitolite repository access configuration.
GL_RC
~~~~~
-This configuration key must point to the file ``gitolite.rc`` used by gitolite
+This configuration key points to the file ``gitolite.rc`` used by gitolite
to record who has access to what (ie: who has access to which repo/branch).
@@ -241,12 +252,12 @@ This configuration key indicates the URL at which the EventSource server is
available. If not defined, pagure will behave as if there are no EventSource
server running.
+
EVENTSOURCE_PORT
~~~~~~~~~~~~~~~~
This configuration key indicates the port at which the EventSource server is
-running. This allows adjusting the port via the configuration file instead
-of hard-coding it in the code.
+running.
.. note:: The EventSource server requires a redis server (see ``Redis options``
below)
@@ -281,7 +292,7 @@ Defaults to: ``0.0.0.0``.
REDIS_PORT
~~~~~~~~~~
-This configuration key indicates the port at which the reds server can be
+This configuration key indicates the port at which the redis server can be
contacted.
Defaults to: ``6379``.
@@ -289,8 +300,8 @@ Defaults to: ``6379``.
REDIS_DB
~~~~~~~~
-This configuration key indicates the name of the redis database to use to
-communicate with the EventSource server.
+This configuration key indicates the name of the redis database to use for
+communicating with the EventSource server.
Defaults to: ``0``.
@@ -301,18 +312,18 @@ Authentication options
ADMIN_GROUP
~~~~~~~~~~~
-List of groups, local or remotes (if the openid server used supports the
-group extension), that are site admin. These admins can regenerate the
-gitolite configuration, the ssh key files, the hook-token for every project
+List of groups, either local or remote (if the openid server used supports the
+group extension), that are the site admins. These admins can regenerate the
+gitolite configuration, the ssh key files, and the hook-token for every project
as well as manage users and groups.
PAGURE_ADMIN_USERS
~~~~~~~~~~~~~~~~~~
-List of usernames that are site admin. These admins have the same rights as
-the user in the admin groups (listed above) as well as admin rights to
-every projects hosted on this pagure instance.
+List of local users that are the site admins. These admins have the same rights as
+the users in the admin groups listed above as well as admin rights to
+all projects hosted on this pagure instance.
Optional options
@@ -338,7 +349,7 @@ Where `` and `` must be replaced by your values.
ITEM_PER_PAGE
~~~~~~~~~~~~~
This configuration key allows you to configure the length of a page by
-setting the number of items on the page. Items can be commits, users, groups
+setting the number of items on the page. Items can be commits, users, groups,
or projects for example.
Defaults to: ``50``.
@@ -347,15 +358,16 @@ Defaults to: ``50``.
SMTP_SERVER
~~~~~~~~~~~
-This configuration key allows one to configure the SMTP server to use when
+This configuration key specifies the SMTP server to use when
sending emails.
Defaults to: ``localhost``.
+
SMTP_PORT
~~~~~~~~~
-This configuration key allows one to define the SMTP server port.
+This configuration key specifies the SMTP server port.
SMTP by default uses TCP port 25. The protocol for mail submission is
the same, but uses port 587.
@@ -364,27 +376,30 @@ SMTP connections secured by SSL, known as SMTPS, default to port 465
Defaults to: ``25``
+
SMTP_SSL
~~~~~~~~
-This configuration key allows one to specify whether the SMTP connections
-should secured over SSL
+This configuration key specifies whether the SMTP connections
+should be secured over SSL.
Defaults to: ``False``
+
SMTP_USERNAME
~~~~~~~~~~~~~
-This configuration key allows usage of SMTP with auth
+This configuration key allows usage of SMTP with auth.
Note: Specify SMTP_USERNAME and SMTP_PASSWORD for using SMTP auth
Defaults to: ``None``
+
SMTP_PASSWORD
~~~~~~~~~~~~~
-This configuration key allows usage of SMTP with auth
+This configuration key allows usage of SMTP with auth.
Note: Specify SMTP_USERNAME and SMTP_PASSWORD for using SMTP auth
@@ -393,7 +408,7 @@ Defaults to: ``None``
SHORT_LENGTH
~~~~~~~~~~~~
-This configuration key allows one to configure the length of the commit ids or
+This configuration key specifies the length of the commit ids or
file hex displayed in the user interface.
Defaults to: ``6``.
@@ -402,7 +417,7 @@ Defaults to: ``6``.
BLACKLISTED_PROJECTS
~~~~~~~~~~~~~~~~~~~~
-This configuration key allows one to set a list of project name that are forbidden.
+This configuration key specifies a list of project names that are forbidden.
This list is used for example to avoid conflicts at the URL level between the
static files located under ``/static/`` and a project that would be named
``static`` and thus be located at ``/static``.
@@ -421,10 +436,10 @@ Defaults to:
CHECK_SESSION_IP
~~~~~~~~~~~~~~~~
-This configuration key allows one to configure whether to check the user's IP
+This configuration key specifies whether to check the user's IP
address when retrieving its session. This makes things more secure but
-under certain setup it might not work (for example if there are proxies
-in front of the application).
+under certain setups it might not work (for example if there
+are proxies in front of the application).
Defaults to: ``True``.
@@ -432,10 +447,10 @@ Defaults to: ``True``.
PAGURE_AUTH
~~~~~~~~~~~~
-This configuration key allows one to specify which authentication method to use.
-Pagure supports currently two authentication methods, one relying on the
+This configuration key specifies which authentication method to use.
+Pagure currently supports two authentication methods: one relying on the
Fedora Account System `FAS `_,
-the other relying on local user accounts.
+and the other using only the local database.
It can therefore be either ``fas`` or ``local``.
Defaults to: ``fas``.
@@ -444,11 +459,11 @@ Defaults to: ``fas``.
IP_ALLOWED_INTERNAL
~~~~~~~~~~~~~~~~~~~
-This configuration key allows one to specify which IP addresses are allowed
+This configuration key specifies which IP addresses are allowed
to access the internal API endpoint. These endpoints are accessed by the
-milters for example and allow one to perform action in the name of someone else.
-So they are sensitive, thus the check for the origin of the request using
-these endpoints.
+milters for example and allow performing actions in the name of someone else
+which is sensitive, thus the origin of the request using
+these endpoints is validated.
Defaults to: ``['127.0.0.1', 'localhost', '::1']``.
@@ -456,7 +471,7 @@ Defaults to: ``['127.0.0.1', 'localhost', '::1']``.
MAX_CONTENT_LENGTH
~~~~~~~~~~~~~~~~~~
-This configuration key allows one to specify the maximum size allowed when
+This configuration key specifies the maximum file size allowed when
uploading content to pagure (for example, screenshots to a ticket).
Defaults to: ``4 * 1024 * 1024`` which corresponds to 4 megabytes.
@@ -465,7 +480,7 @@ Defaults to: ``4 * 1024 * 1024`` which corresponds to 4 megabytes.
ENABLE_TICKETS
~~~~~~~~~~~~~~
-This configuration key allows one to activate or de-activate the ticketing system
+This configuration key activates or de-activates the ticketing system
for all the projects hosted on this pagure instance.
Defaults to: ``True``
@@ -474,7 +489,7 @@ Defaults to: ``True``
ENABLE_NEW_PROJECTS
~~~~~~~~~~~~~~~~~~~
-This configuration key allows one to create or forbids creating new projects in
+This configuration key permits or forbids creation of new projects via
the user interface of this pagure instance.
Defaults to: ``True``
@@ -483,7 +498,7 @@ Defaults to: ``True``
ENABLE_DEL_PROJECTS
~~~~~~~~~~~~~~~~~~~
-This configuration key allows one to delete or forbids deleting projects in
+This configuration key permits or forbids deletiion of projects via
the user interface of this pagure instance.
Defaults to: ``True``
@@ -492,7 +507,7 @@ Defaults to: ``True``
EMAIL_SEND
~~~~~~~~~~
-This configuration key allows turning on or off all email notification for
+This configuration key enables or disables all email notifications for
this pagure instance. This can be useful to turn off when developing on
pagure, or for test or pre-production instances.
@@ -513,7 +528,7 @@ we added an endpoint ``view_commit_old`` that brings URL backward
compatibility for URLs using the complete git hash (the 40 characters).
For URLs using a shorter hash, the URLs will remain broken.
-This configuration key allows turning on or off this backward compatibility
+This configuration key enables or disables this backward compatibility
which is useful for pagure instances running since before 1.3 but is not
for newer instances.