Configuration ============= Pagure offers a wide varieties of options that must or can be used to adjust its behavior. Must options ------------ 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 and set as a long and random string. SALT_EMAIL ~~~~~~~~~~ This key is used for when sending notification 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 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. Examples values: :: 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`` APP_URL ~~~~~~~ This key indicates the URL at which this pagure instance will be made available. 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 present in the logs). This setting allows you to specify to which email address to send these error reports. GIT_URL_SSH ~~~~~~~~~~~ This configuration key provides the information to the user on how to clone the git repos hosted on pagure via `SSH `_. The URL should end with a slash ``/``. Defaults to: ``'ssh://git@pagure.org/'`` GIT_URL_GIT ~~~~~~~~~~~ This configuration key provides the information to the user on how to clone the git repos hosted on pagure anonymously. This access can be granted via the ``git://`` or ``http(s)://`` protocols. 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. 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 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). FORK_FOLDER ~~~~~~~~~~~ This configuration key points to the folder where the git repos of forks of the projects are stored. DOCS_FOLDER ~~~~~~~~~~~ This configuration key points to the folder where the git repos for the documentation of the projects are stored. TICKETS_FOLDER ~~~~~~~~~~~~~~ This configuration key points to the folder where the git repos storing 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 metadata of the pull-requests opened against the project are stored. REMOTE_GIT_FOLDER ~~~~~~~~~~~~~~~~~ This configuration key points to the folder where the remote git repos (ie: not hosted on pagure) that someone used to open a pull-request against a project hosted on pagure are stored. SESSION_COOKIE_SECURE ~~~~~~~~~~~~~~~~~~~~~ When this is set to True, the session cookie will only be returned to the server via ssl (https). If you connect to the server via plain http, the cookie will not be sent. This prevents sniffing of the cookie contents. This may be set to False when testing your application but should always be set to True in production. Defaults to: ``False`` for development, must be ``True`` in production with https. FROM_EMAIL ~~~~~~~~~~ This setting allows one to specify the email address used by this pagure instance when sending emails (notifications). 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 when building the ``msg-id`` header of the emails sent. Defaults to: ``pagure.org`` VIRUS_SCAN_ATTACHMENTS ~~~~~~~~~~~~~~~~~~~~~~ This setting configures whether attachments are scanned for viruses on upload. For more information, see the install.rst guide. Defaults to: ``False`` Configure Gitolite ------------------ Pagure uses `gitolite `_ as an authorization layer. Gitolite relies on `SSH `_ for the authentication. In other words, SSH let you in and gitolite check if you 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 ran. GITOLITE_VERSION ~~~~~~~~~~~~~~~~ This configuration key allows one to specify which version of gitolite you are using, it can be either ``2`` or ``3``. Defaults to: ``3``. GITOLITE_KEYDIR ~~~~~~~~~~~~~~~ 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. GL_RC ~~~~~ This configuration key must point to the file ``gitolite.rc`` used by gitolite to record who has access to what (ie: who has access to which repo/branch). GL_BINDIR ~~~~~~~~~ This configuration key indicates the folder in which the gitolite tools can be found. It can be as simple as ``/usr/bin/`` if the tools have been installed using a package manager or something like ``/opt/bin/`` for a more custom install. EventSource options ------------------- EVENTSOURCE_SOURCE ~~~~~~~~~~~~~~~~~~ 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. .. note:: The EventSource server requires a redis server (see ``Redis options`` below) Web-hooks notifications ----------------------- WEBHOOK ~~~~~~~ This configuration key allows turning on or off web-hooks notifications for this pagure instance. Defaults to: ``False``. .. note:: The Web-hooks server requires a redis server (see ``Redis options`` below) Redis options ------------- REDIS_HOST ~~~~~~~~~~ This configuration key indicates the host at which the `redis `_ server is running. Defaults to: ``0.0.0.0``. REDIS_PORT ~~~~~~~~~~ This configuration key indicates the port at which the reds server can be contacted. Defaults to: ``6379``. REDIS_DB ~~~~~~~~ This configuration key indicates the name of the redis database to use to communicate with the EventSource server. Defaults to: ``0``. 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 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. Optional options ---------------- SSH_KEYS ~~~~~~~~ It is a good pratice to publish the fingerprint and public SSH key of a server you provide access to. Pagure offers the possibility to expose this information based on the values set in the configuration file, in the ``SSH_KEYS`` configuration key. See the `SSH hostkeys/Fingerprints page on pagure.io `_. .. warning: The format is important SSH_KEYS = {'RSA': {'fingerprint': '', 'pubkey': ''}} 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 or projects for example. Defaults to: ``50``. SMTP_SERVER ~~~~~~~~~~~ This configuration key allows one to configure the SMTP server to use when sending emails. Defaults to: ``localhost``. SMTP_PORT ~~~~~~~~~ This configuration key allows one to define the SMTP server port. SMTP by default uses TCP port 25. The protocol for mail submission is the same, but uses port 587. SMTP connections secured by SSL, known as SMTPS, default to port 465 (nonstandard, but sometimes used for legacy reasons). Defaults to: ``25`` SMTP_SSL ~~~~~~~~ This configuration key allows one to specify whether the SMTP connections should secured over SSL Defaults to: ``False`` SMTP_USERNAME ~~~~~~~~~~~~~ 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 Note: Specify SMTP_USERNAME and SMTP_PASSWORD for using SMTP auth Defaults to: ``None`` SHORT_LENGTH ~~~~~~~~~~~~ This configuration key allows one to configure the length of the commit ids or file hex displayed in the user interface. Defaults to: ``6``. BLACKLISTED_PROJECTS ~~~~~~~~~~~~~~~~~~~~ This configuration key allows one to set a list of project name 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``. Defaults to: :: [ 'static', 'pv', 'releases', 'new', 'api', 'settings', 'logout', 'login', 'users', 'groups' ] CHECK_SESSION_IP ~~~~~~~~~~~~~~~~ This configuration key allows one to configure 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). 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 Fedora Account System `FAS `_, the other relying on local user accounts. It can therefore be either ``fas`` or ``local``. Defaults to: ``fas``. IP_ALLOWED_INTERNAL ~~~~~~~~~~~~~~~~~~~ This configuration key allows one to specify 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. Defaults to: ``['127.0.0.1', 'localhost', '::1']``. MAX_CONTENT_LENGTH ~~~~~~~~~~~~~~~~~~ This configuration key allows one to specify the maximum size allowed when uploading content to pagure (for example, screenshots to a ticket). 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 for all the projects hosted on this pagure instance. Defaults to: ``True`` ENABLE_NEW_PROJECTS ~~~~~~~~~~~~~~~~~~~ This configuration key allows one to create or forbids creating new projects in the user interface of this pagure instance. Defaults to: ``True`` ENABLE_DEL_PROJECTS ~~~~~~~~~~~~~~~~~~~ This configuration key allows one to delete or forbids deleting projects in the user interface of this pagure instance. Defaults to: ``True`` EMAIL_SEND ~~~~~~~~~~ This configuration key allows turning on or off all email notification for this pagure instance. This can be useful to turn off when developing on pagure, or for test or pre-production instances. Defaults to: ``True``. OLD_VIEW_COMMIT_ENABLED ~~~~~~~~~~~~~~~~~~~~~~~ In version 1.3, pagure changed its URL scheme to view the commit of a project in order to add support for pseudo-namespaced projects. For pagure instances older than 1.3, who care about backward compatibility, 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 which is useful for pagure instances running since before 1.3 but is not for newer instances. Defaults to: ``False``. PAGURE_CI_SERVICES ~~~~~~~~~~~~~~~~~~ Pagure can be configure to integrate results of a Continuous Integration (CI) service to pull-requests open against a project. To enable this integration, follow the documentation on how to install pagure-ci and set this configuration key to ``['jenkins']`` (Jenkins being the only CI service supported at the moment). Defaults to: ``None``. .. warning:: Requires `Redis` to be configured and running.