config: clarify that we only recommend and support single threaded operation

Sad, but true. Especially because we reuse Repository instances between
threads.

development.ini

@@ -70,16 +70,16 b' pdebug = false'
 ## PASTE ##
 #use = egg:Paste#http
 ## nr of worker threads to spawn
-#threadpool_workers = 5
+#threadpool_workers = 1
 ## max request before thread respawn
-#threadpool_max_requests = 10
+#threadpool_max_requests = 100
 ## option to use threads of process
 #use_threadpool = true
 
 ## WAITRESS ##
 use = egg:waitress#main
 ## number of worker threads
-threads = 5
+threads = 1
 ## MAX BODY SIZE 100GB
 max_request_body_size = 107374182400
 ## use poll instead of select, fixes fd limits, may not work on old

docs/setup.rst

@@ -785,8 +785,7 b' Here is a sample excerpt from an Apache '
 
 .. code-block:: apache
 
-    WSGIDaemonProcess kallithea \
-        threads=4 \
+    WSGIDaemonProcess kallithea processes=5 threads=1 maximum-requests=100 \
         python-home=/srv/kallithea/venv
     WSGIProcessGroup kallithea
     WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
@@ -796,7 +795,7 b' Or if using a dispatcher WSGI script wit'
 
 .. code-block:: apache
 
-    WSGIDaemonProcess kallithea threads=4
+    WSGIDaemonProcess kallithea processes=5 threads=1 maximum-requests=100
     WSGIProcessGroup kallithea
     WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
     WSGIPassAuthorization On

docs/usage/performance.rst

@@ -31,8 +31,26 b' 4. Scale Kallithea horizontally'
 
     Scaling horizontally can give huge performance benefits when dealing with
     large amounts of traffic (many users, CI servers, etc.). Kallithea can be
-    scaled horizontally on one (recommended) or multiple machines. In order
-    to scale horizontally you need to do the following:
+    scaled horizontally on one (recommended) or multiple machines.
+
+    It is generally possible to run WSGI applications multithreaded, so that
+    several HTTP requests are served from the same Python process at once. That
+    can in principle give better utilization of internal caches and less
+    process overhead.
+    
+    One danger of running multithreaded is that program execution becomes much
+    more complex; programs must be written to consider all combinations of
+    events and problems might depend on timing and be impossible to reproduce.
+
+    Kallithea can't promise to be thread-safe, just like the embedded Mercurial
+    backend doesn't make any strong promises when used as Kallithea uses it.
+    Instead, we recommend scaling by using multiple server processes.
+
+    Web servers with multiple worker processes (such as ``mod_wsgi`` with the
+    ``WSGIDaemonProcess`` ``processes`` parameter) will work out of the box.
+
+    In order to scale horizontally on multiple machines, you need to do the
+    following:
 
     - Each instance's ``data`` storage needs to be configured to be stored on a
       shared disk storage, preferably together with repositories. This ``data``
@@ -40,7 +58,7 b' 4. Scale Kallithea horizontally'
       task locking (so it is safe across multiple instances). Set the
       ``cache_dir``, ``index_dir``, ``beaker.cache.data_dir``, ``beaker.cache.lock_dir``
       variables in each .ini file to a shared location across Kallithea instances
-    - If celery is used each instance should run a separate Celery instance, but
+    - If using several Celery instances,
       the message broker should be common to all of them (e.g.,  one
       shared RabbitMQ server)
     - Load balance using round robin or IP hash, recommended is writing LB rules

kallithea/bin/template.ini.mako

@@ -65,9 +65,9 b' pdebug = false'
 <%text>## PASTE ##</%text>
 use = egg:Paste#http
 <%text>## nr of worker threads to spawn</%text>
-threadpool_workers = 5
+threadpool_workers = 1
 <%text>## max request before thread respawn</%text>
-threadpool_max_requests = 10
+threadpool_max_requests = 100
 <%text>## option to use threads of process</%text>
 use_threadpool = true
 
@@ -75,7 +75,7 b' use_threadpool = true'
 <%text>## WAITRESS ##</%text>
 use = egg:waitress#main
 <%text>## number of worker threads</%text>
-threads = 5
+threads = 1
 <%text>## MAX BODY SIZE 100GB</%text>
 max_request_body_size = 107374182400
 <%text>## use poll instead of select, fixes fd limits, may not work on old</%text>

kallithea/config/deployment.ini_tmpl

@@ -65,16 +65,16 b' pdebug = false'
 ## PASTE ##
 #use = egg:Paste#http
 ## nr of worker threads to spawn
-#threadpool_workers = 5
+#threadpool_workers = 1
 ## max request before thread respawn
-#threadpool_max_requests = 10
+#threadpool_max_requests = 100
 ## option to use threads of process
 #use_threadpool = true
 
 ## WAITRESS ##
 use = egg:waitress#main
 ## number of worker threads
-threads = 5
+threads = 1
 ## MAX BODY SIZE 100GB
 max_request_body_size = 107374182400
 ## use poll instead of select, fixes fd limits, may not work on old

kallithea/tests/test.ini

@@ -68,16 +68,16 b' pdebug = false'
 ## PASTE ##
 #use = egg:Paste#http
 ## nr of worker threads to spawn
-#threadpool_workers = 5
+#threadpool_workers = 1
 ## max request before thread respawn
-#threadpool_max_requests = 10
+#threadpool_max_requests = 100
 ## option to use threads of process
 #use_threadpool = true
 
 ## WAITRESS ##
 use = egg:waitress#main
 ## number of worker threads
-threads = 5
+threads = 1
 ## MAX BODY SIZE 100GB
 max_request_body_size = 107374182400
 ## use poll instead of select, fixes fd limits, may not work on old