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 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 configuration key is used to ensure that when sending

notifications to different users, each one of them has a different, unique

and unfakeable ``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 configuration key indicates to the framework how and where to connect to the database

server. Pagure uses `SQLAchemy <http: www.sqlalchemy.org="">`_ to connect</http:>

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 configuration key indicates the URL at which this pagure instance will be made available.

Defaults to: ``http://localhost.localdomain/``

EMAIL_ERROR

~~~~~~~~~~~

Pagure sends email when it catches an unexpected error (which saves you from

having to monitor the logs regularly; but if you like, the error is still

present in the logs).

This configuration key 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 <https: en.wikipedia.org="" secure_shell="" wiki="">`_.</https:>

The URL should end with a slash ``/``.

Defaults to: ``'ssh://git@llocalhost.localdomain/'``

.. note:: If you are using a custom setup for your deployment where every

        user has an account on the machine you may want to tweak this URL

        to include the username. If that is the case, you can use

        ``{username}`` in the URL and it will be expanded to the username

        of the user viewing the page when rendered.

        For example: ``'ssh://{username}@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://localhost.localdomain/'``

BROKER_URL

~~~~~~~~~~

This configuration key is used to point celery to the broker to use. This

is the broker that is used to communicate between the web application and

its workers.

Defaults to: ``'redis://%s' % APP.config['REDIS_HOST']``

.. note:: See the :ref:`redis-section` for the ``REDIS_HOST`` configuration

          key

Repo Directories

----------------

Each project in pagure has 2 to 4 git repositories, depending on configuration

of the Pagure instance (see below):

- the main repo for the code

- the doc repo showed in the doc server (optional)

- the ticket repo storing the metadata of the tickets (optional)

- the request repo storing the metadata of the pull-requests

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.

GIT_FOLDER

~~~~~~~~~~

This configuration key points to the folder where the git repos are stored.

For every project, two to four repos are created:

* a repo with source code of the project

* a repo with documentation of the project

  (if ``ENABLE_DOCS`` is ``True``)

* a repo with metadata of tickets opened against the project

  (if ``ENABLE_TICKETS`` is ``True``)

* a repo with metadata of pull requests opened against the project

Note that gitolite config value ``GL_REPO_BASE`` (if using gitolite 3)

or ``$REPO_BASE`` (if using gitolite 2) **must** have exactly the same

value as ``GIT_FOLDER``.

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.

UPLOAD_FOLDER_PATH

~~~~~~~~~~~~~~~~~~

This configuration key points to the folder where user-uploaded tarballs

are stored and served from.

ATTACHMENTS_FOLDER

~~~~~~~~~~~~~~~~~~

This configuration key points to the folder where attachments can be cached

for easier access by the web-server (allowing to not interact with the git

repo having it to serve it).

UPLOAD_FOLDER_URL

~~~~~~~~~~~~~~~~~~

Full URL to where the uploads are available. It is highly recommended for

security reasons that this URL lives on a different domain than the main

application (an entirely different domain, not just a sub-domain).

Defaults to: ``/releases/``, unsafe for production!

.. warning:: both `UPLOAD_FOLDER_PATH` and `UPLOAD_FOLDER_URL` must be

            specified for the upload release feature to work

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.

SESSION_TYPE

~~~~~~~~~~~~

Enables the `flask-session <https: flask-session="" pythonhosted.org="">`_</https:>

extension if set to a value other than ``None``. The ``flask-session``

package needs to be installed and proper

`configuration <https: #configuration="" flask-session="" pythonhosted.org="">`_</https:>

needs to be included in the Pagure config file.

This is useful when the Pagure server needs to be scaled up to multiple

instances, which requires the flask session keys to be shared between those.

Flask-session allows you to use Redis, Memcached, relational database

or MongoDB for storing shared session keys.

FROM_EMAIL

~~~~~~~~~~

This configuration key specifies the email address used by this pagure instance

when sending emails (notifications).

Defaults to: ``pagure@localhost.localdomain``

DOMAIN_EMAIL_NOTIFICATIONS

~~~~~~~~~~~~~~~~~~~~~~~~~~

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: ``localhost.localdomain``

VIRUS_SCAN_ATTACHMENTS

~~~~~~~~~~~~~~~~~~~~~~

This configuration key configures whether attachments are scanned for viruses on

upload. For more information, see the install.rst guide.

Defaults to: ``False``

GIT_AUTH_BACKEND

^^^^^^^^^^^^^^^^

This configuration key allows specifying which git auth backend to use.

Git auth backends can either be static (like gitolite), where a file is

generated when something changed and then used on login, or dynamic,

where the actual ACLs are checked in a git hook before being applied.

By default pagure provides the following backends:

- `test_auth`: simple debugging backend printing and returning the string ``Called GitAuthTestHelper.generate_acls()``

- `gitolite2`: allows deploying pagure on the top of gitolite 2

- `gitolite3`: allows deploying pagure on the top of gitolite 3

Defaults to: ``gitolite3``

.. note:: The option GITOLITE_BACKEND is the legacy name, and for backwards compatibility reasons will override this setting

.. note:: These options can be expended, cf :ref:`custom-gitolite`.

Configure Gitolite

------------------

Pagure can use `gitolite <http: gitolite.com="">`_ as an authorization layer.</http:>

Gitolite relies on `SSH <https: en.wikipedia.org="" secure_shell="" wiki="">`_ for</https:>

the authentication. In other words, SSH lets you in and gitolite checks if

you are allowed to do what you are trying to do once you are inside.

Pagure supports both gitolite 2 and gitolite 3 and the code generating

the gitolite configuration can be customized for easier integration with

other systems (cf :ref:`custom-gitolite`).

**gitolite 2 and 3**

~~~~~~~~~~~~~~~~~~~~

GITOLITE_HOME

^^^^^^^^^^^^^

This configuration key points to the home directory of the user under which

gitolite is ran.

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.

GITOLITE_CONFIG

^^^^^^^^^^^^^^^

This configuration key points to the gitolite.conf file where pagure writes

the gitolite repository access configuration.

GITOLITE_CELERY_QUEUE

^^^^^^^^^^^^^^^^^^^^^

This configuration is useful for large pagure deployment where recompiling

the gitolite config file can take a long time. By default the compilation

of gitolite's configuration file is done by the pagure_worker, which spawns

by default 4 concurrent workers. If it takes a while to recompile the

gitolite configuration file, these workers may be stepping on each others'

toes.

In this situation, this configuration key allows you to direct the messages

asking for the gitolite configuration file to be compiled to a different

queue which can then be handled by a different service/worker.

Pagure provides a ``pagure_gitolite_worker.service`` systemd service file

pre-configured to handles these messages if this configuration key is set

to ``gitolite_queue``.

**gitolite 2 only**

~~~~~~~~~~~~~~~~~~~

GL_RC

^^^^^

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).

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.

**gitolite 3 only**

~~~~~~~~~~~~~~~~~~~

GITOLITE_HAS_COMPILE_1

^^^^^^^^^^^^^^^^^^^^^^

By setting this configuration key to ``True``, you can turn on using the

gitolite ``compile-1`` binary. This speeds up gitolite task when it recompiles

configuration after new project is created. In order to use this, you need to

have the ``compile-1`` gitolite command.

There are two ways to have it,

#. You distribution already has the file installed for you and you can then

   just use it.

#. You need to download and install it yourself. We are describing what

   needs to be done for this here below.

Installing the ``compile-1`` command:

* You also have to make sure that your distribution of gitolite contains

  `patch <https: c4b6521a4b82e639f6ed776abad79c="" commit="" github.com="" gitolite="" sitaramc="">`_</https:>

  which makes gitolite respect ``ALLOW_ORPHAN_GL_CONF`` configuration variable,

  if this patch isn't already present, you will have to make the change yourself.

* In your ``gitolite.rc`` set ``ALLOW_ORPHAN_GL_CONF`` to ``1`` (you may

  have to add it yourself).

* Still in your ``gitolite.rc`` file, uncomment ``LOCAL_CODE`` file and set

  it to a full path of a directory that you choose (for example

  ``/usr/local/share/gitolite3``).

* Create a subdirectory ``commands`` under the path you picked for ``LOCAL_CODE``

  (in our example, you will need to do: ``mkdir -p /usr/local/share/gitolite3/commands``)

* Finally, install the ``compile-1`` command in this ``commands`` subdirectory

  If your installation doesn't ship this file, you can `download it

  <https: blob="" commands="" compile-1="" contrib="" github.com="" gitolite="" master="" sitaramc="">`_.</https:>

  (Ensure the file is executable, otherwise gitolite will not find it)

Defaults to: ``False``

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.

.. 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-section:

Redis options

-------------

REDIS_HOST

~~~~~~~~~~

This configuration key indicates the host at which the `redis <http: redis.io="">`_</http:>

server is running.

Defaults to: ``0.0.0.0``.

REDIS_PORT

~~~~~~~~~~

This configuration key indicates the port at which the redis server can be

contacted.

Defaults to: ``6379``.

REDIS_DB

~~~~~~~~

This configuration key indicates the name of the redis database to use for

communicating with the EventSource server.

Defaults to: ``0``.

Authentication options

----------------------

ADMIN_GROUP

~~~~~~~~~~~

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 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.

Celery Queue options

--------------------

In order to help prioritize between tasks having a direct impact on the user

experience and tasks needed to be run on the background but not directly

impacting the users, we have split the generic tasks triggered by the web

application into three possible queues: Fast, Medium, Slow.

If none of these options are set, a single queue will be used for all tasks.

FAST_CELERY_QUEUE

~~~~~~~~~~~~~~~~~

This configuration key allows to specify a dedicated queue for tasks that

are triggered by the web frontend and need to be processed quickly for the

best user experience.

This will be used for tasks such as creating a new project, forking or

merging a pull-request.

Defaults to: ``None``.

MEDIUM_CELERY_QUEUE

~~~~~~~~~~~~~~~~~~~

This configuration key allows to specify a dedicated queue for tasks that

are triggered by the web frontend and need to be processed but aren't critical

for the best user experience.

This will be used for tasks such as updating a file in a git repository.

Defaults to: ``None``.

SLOW_CELERY_QUEUE

~~~~~~~~~~~~~~~~~

This configuration key allows to specify a dedicated queue for tasks that

are triggered by the web frontend, are slow and do not impact the user

experience in the user interface.

This will be used for tasks such as updating the ticket git repo based on

the content posted in the user interface.

Defaults to: ``None``.

Stomp Options

-------------

Pagure integration with Stomp allows you to emit messages to any

stomp-compliant message bus.

STOMP_NOTIFICATIONS

~~~~~~~~~~~~~~~~~~~

This configuration key allows to turn on or off notifications via

`stomp protocol <https: stomp.github.io="">`_. All other stomp-related</https:>

settings don't need to be present if this is set to ``False``.

Defaults to: ``False``.

STOMP_BROKERS

~~~~~~~~~~~~~

List of 2-tuples with broker domain names and ports. For example

``[('primary.msg.bus.com', 6543), ('backup.msg.bus.com`, 6543)]``.

STOMP_HIERARCHY

~~~~~~~~~~~~~~~

Base name of the hierarchy to emit messages to. For example

``/queue/some.hierarchy.``. Note that this **must** end with

a dot. Pagure will append queue names such as ``project.new``

to this value, resulting in queue names being e.g.

``/queue/some.hierarchy.project.new``.

STOMP_SSL

~~~~~~~~~

Whether or not to use SSL when connecting to message brokers.

Defaults to: ``False``.

STOMP_KEY_FILE

~~~~~~~~~~~~~~

Absolute path to key file for SSL connection. Only required if

``STOMP_SSL`` is set to ``True``.

STOMP_CERT_FILE

~~~~~~~~~~~~~~~

Absolute path to certificate file for SSL connection. Only required if

``STOMP_SSL`` is set to ``True``.

STOMP_CREDS_PASSWORD

~~~~~~~~~~~~~~~~~~~~

Password for decoding ``STOMP_CERT_FILE`` and ``STOMP_KEY_FILE``. Only

required if ``STOMP_SSL`` is set to ``True`` and credentials files are

password-encoded.

API token ACLs

--------------

ACLS

~~~~

This configuration key lists all the ACLs that can be associated with an API

token with a short description of what the ACL allows to do.

This key it not really meant to be changed unless you really know what you

are doing.

USER_ACLS

~~~~~~~~~

This configuration key allows to list which of the ACLs listed in ``ACLS``

can be associated with an API token of a project in the (web) user interface.

Use this configuration key in combination with ``ADMIN_API_ACLS`` to disable

certain ACLs for users while allowing admins to generate keys with them.

Defaults to: ``[key for key in ACLS.keys() if key != 'generate_acls_project']``

    (ie: all the ACLs in ``ACLS`` except for ``generate_acls_project``)

ADMIN_API_ACLS

~~~~~~~~~~~~~~

This configuration key allows to list which of the ACLs listed in ``ACLS``

can be generated by the ``pagure-admin`` CLI tool by admins.

Defaults to: ``['issue_comment', 'issue_create', 'issue_change_status', 'pull_request_flag', 'pull_request_comment', 'pull_request_merge', 'generate_acls_project', 'commit_flag', 'create_branch']``

CROSS_PROJECT_ACLS

~~~~~~~~~~~~~~~~~~

This configuration key allows to list which of the ACLs listed in ``ACLS``

can be associated with a project-less API token in the (web) user interface.

These project-less API tokens can be generated in the user's settings page

and allows action in multiple projects instead of being restricted to a

specific one.

Defaults to: ``['create_project', 'fork_project', 'modify_project']``

Optional options

----------------

Git repository templates

~~~~~~~~~~~~~~~~~~~~~~~~

PROJECT_TEMPLATE_PATH

^^^^^^^^^^^^^^^^^^^^^

This configuration key allows you to specify the path to a git repository

to use as a template when creating new repository for new projects.

This template will not be used for forks nor any of the git repository but

the one used for the sources (ie: it will not be used for the tickets,

requests or docs repositories).

FORK_TEMPLATE_PATH

^^^^^^^^^^^^^^^^^^

This configuration key allows you to specify the path to a git repository

to use as a template when creating new repository for new forks.

This template will not be used for any of the git repository but

the one used for the sources of forks (ie: it will not be used for the

tickets, requests or docs repositories).

SSH_KEYS

~~~~~~~~

It is a good practice 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 <https: pagure.io="" ssh_info="">`_.</https:>

.. warning: The format is important

    SSH_KEYS = {'RSA': {'fingerprint': '<foo>', 'pubkey': '<bar>'}}</bar></foo>

Where `<foo>` and `<bar>` must be replaced by your values.</bar></foo>

LOGGING

~~~~~~~

This configuration key allows you to set up the logging of the application.

It relies on the standard `python logging module

<https: 2="" docs.python.org="" library="" logging.html="">`_.</https:>

The default value is:

::

    LOGGING = {

        'version': 1,

        'disable_existing_loggers': False,

        'formatters': {

            'standard': {

                'format': '%(asctime)s [%(levelname)s] %(name)s: %(message)s'

            },

            'email_format': {

                'format': MSG_FORMAT

            }

        },

        'filters': {

            'myfilter': {

                '()': ContextInjector,

            }

        },

        'handlers': {

            'console': {

                'level': 'INFO',

                'formatter': 'standard',

                'class': 'logging.StreamHandler',

                'stream': 'ext://sys.stdout',

            },

            'email': {

                'level': 'ERROR',

                'formatter': 'email_format',

                'class': 'logging.handlers.SMTPHandler',

                'mailhost': 'localhost',

                'fromaddr': 'pagure@localhost',

                'toaddrs': 'root@localhost',

                'subject': 'ERROR on pagure',

                'filters': ['myfilter'],

            },

        },

        # The root logger configuration; this is a catch-all configuration

        # that applies to all log messages not handled by a different logger

        'root': {

            'level': 'INFO',

            'handlers': ['console'],

        },

        'loggers': {

            'pagure': {

                'handlers': ['console'],

                'level': 'DEBUG',

                'propagate': True

            },

            'flask': {

                'handlers': ['console'],

                'level': 'INFO',

                'propagate': False

            },

            'sqlalchemy': {

                'handlers': ['console'],

                'level': 'WARN',

                'propagate': False

            },

            'binaryornot': {

                'handlers': ['console'],

                'level': 'WARN',

                'propagate': True

            },

            'pagure.lib.encoding_utils': {

                'handlers': ['console'],

                'level': 'WARN',

                'propagate': False

            },

        }

    }

.. note:: as you can see there is an ``email`` handler defined. It's not used

    anywhere by default but you can use it to get report of errors by email

    and thus monitor your pagure instance.

    To do this the easiest is to set, on the ``root`` logger:

    ::

        'handlers': ['console', 'email'],

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``.

PR_TARGET_MATCHING_BRANCH

~~~~~~~~~~~~~~~~~~~~~~~~~

If set to ``True``, the default target branch for all pull requests in UI

is the branch that is longest substring of the branch that the pull request

is created from. For example, a ``mybranch`` branch in original repo will

be the default target of a pull request from branch ``mybranch-feature-1``

in a fork when opening a new pull request. If this is set to ``False``,

the default branch of the repo will be the default target of all pull requests.

Defaults to: ``False``.

SMTP_SERVER

~~~~~~~~~~~

This configuration key specifies the SMTP server to use when

sending emails.

Defaults to: ``localhost``.

SMTP_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.

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 specifies whether the SMTP connections

should be 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 specifies the length of the commit ids or

file hex displayed in the user interface.

Defaults to: ``6``.

BLACKLISTED_PROJECTS

~~~~~~~~~~~~~~~~~~~~

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``.

Defaults to:

::

    [

        'static', 'pv', 'releases', 'new', 'api', 'settings',

        'logout', 'login', 'users', 'groups'

    ]

CHECK_SESSION_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 setups it might not work (for example if there

are proxies in front of the application).

Defaults to: ``True``.

PAGURE_AUTH

~~~~~~~~~~~~

This configuration key specifies which authentication method to use.

Valid options are ``fas``, ``openid``, ``oidc``, or ``local``.

* ``fas`` uses the Fedora Account System `FAS <https: accounts="" admin.fedoraproject.org="">`</https:>

  to provide user authentication and enforces that users sign the FPCA.

* ``openid`` uses OpenID authentication.  Any provider may be used by

  changing the FAS_OPENID_ENDPOINT configuration key.  By default

  FAS (without FPCA) will be used.

* ``oidc`` enables OpenID Connect using any provider.  This provider requires

  the configuration options starting with ``OIDC_`` (see below) to be provided.

* ``local`` causes pagure to use the local pagure database for user management.

Defaults to: ``local``.

OIDC Settings

~~~~~~~~~~~~~

.. note:: Pagure uses `flask-oidc <https: flask-oidc="" github.com="" puiterwijk="">`_</https:>

   to support OIDC authentication. This extension has a `number of configuration

   keys <http: #settings-reference="" en="" flask-oidc.readthedocs.io="" latest="">`_</http:>