From b9acae29dddb0c36ff7162c66368188e219f29bf Mon Sep 17 00:00:00 2001
From: Pierre-Yves Chibon <pingou@pingoured.fr>
Date: Sep 24 2018 18:42:02 +0000
Subject: Document the configuration keys for repoSpanner


Fixes https://pagure.io/pagure/issue/3640

Signed-off-by: Pierre-Yves Chibon <pingou@pingoured.fr>

---

diff --git a/doc/configuration.rst b/doc/configuration.rst
index 18fd5bb..6a4c885 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -1456,6 +1456,86 @@ watching commits on a project upon commits.
 Defaults to: ``True``
 
 
+RepoSpanner Options
+-------------
+
+Pagure can be integrated with `repoSpanner <https://repospanner.org>`_
+allowing to deploy pagure in a load-balanced environment since the git
+repositories are then synced accross multiple servers simultaneously.
+
+Support for this integration has been included in Pagure version 5.0 and higher.
+
+Here below are the different options one can/should use to integrate pagure
+with repoSpanner.
+
+REPOSPANNER_NEW_REPO
+~~~~~~~~~~~~~~~~~~~~
+
+This configuration key instructs pagure to create new git repositories on
+repoSpanner or not.
+Its value should be the region in which the new git repositories should be
+created on.
+
+Defaults to: ``None``.
+
+REPOSPANNER_NEW_REPO_ADMIN_OVERRIDE
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This configuration key can be used to let pagure admin override the default
+region used when creating new git repositories on repoSpanner.
+Its value should be a boolean.
+
+Defaults to: ``False``
+
+REPOSPANNER_NEW_FORK
+~~~~~~~~~~~~~~~~~~~~
+
+This configuration key instructs pagure on where/how to create new git
+repositories for the forks with repoSpanner.
+If ``None``, git repositories for forks are created outside of repoSpanner
+entirely.
+If ``True``, git repositories for forks are created in the same region as
+the parent project.
+Otherwise, a region can be directly specified where git repositories for
+forks will be created.
+
+Defaults to: ``True``
+
+REPOSPANNER_ADMIN_MIGRATION
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This configuration key can be used to let admin manually migrate individual
+project into repoSpanner once it is set up.
+
+Defaults to: ``False``
+
+REPOSPANNER_REGIONS
+~~~~~~~~~~~~~~~~~~~
+
+This configuration key allows to specify the different region where repoSpanner
+is deployed and thus with which this pagure instance can be integrated.
+
+An example entry could look like:
+
+::
+
+    REPOSPANNER_REGIONS = {
+        'default': {'url': 'https://nodea.regiona.repospanner.local:8444',
+                    'repo_prefix': 'pagure/',
+                    'hook': None,
+                    'ca': '/etc/pki/repospanner/pki/ca.crt',
+                    'admin_cert': {'cert': '/etc/pki/repospanner/pki/admin.crt',
+                                   'key': '/etc/pki/repospanner/pki/admin.key'},
+                    'push_cert': {'cert': '/etc/pki/repospanner/pki/pagure.crt',
+                                  'key': '/etc/pki/repospanner/pki/pagure.key'}}
+    }
+
+If this configuration key is not defined, pagure will consider that it is
+not set to be integrated with repoSpanner.
+
+Defaults to: ``{}``
+
+
 Deprecated configuration keys
 -----------------------------