# HG changeset patch
# User Mads Kiilerich <mads@kiilerich.com>
# Date 1587581222 -7200
# Node ID 4869a8bb1237022f35a2edeffeaf83c375b7dd41
# Parent  238885eaead47cc1ba33809dc89e0cca3e4ec683
ini: tweak template configuration for TG's handling of application errors

Mention what was learned while debugging request processing at WSGI/TG level
and the complexity of the TG stack gets in the way.

diff -r 238885eaead4 -r 4869a8bb1237 development.ini
--- a/development.ini	Wed Apr 22 20:53:22 2020 +0200
+++ b/development.ini	Wed Apr 22 20:47:02 2020 +0200
@@ -318,9 +318,22 @@
 #session.sa.url = postgresql://postgres:qwe@localhost/kallithea
 #session.table_name = db_session
 
-############################
-## ERROR HANDLING SYSTEMS ##
-############################
+####################################
+###       ERROR HANDLING        ####
+####################################
+
+## Show a nice error page for application HTTP errors and exceptions (default true)
+#errorpage.enabled = true
+
+## Enable Backlash client-side interactive debugger (default false)
+## WARNING: *THIS MUST BE false IN PRODUCTION ENVIRONMENTS!!!*
+## This debug mode will allow all visitors to execute malicious code.
+#debug = false
+debug = true
+
+## Enable Backlash server-side error reporting (unless debug mode handles it client-side) (default true)
+#trace_errors.enable = true
+## Errors will be reported by mail if trace_errors.error_email is set.
 
 ## Propagate email settings to ErrorReporter of TurboGears2
 ## You do not normally need to change these lines
@@ -332,13 +345,6 @@
 get trace_errors.smtp_password = smtp_password
 get trace_errors.smtp_use_tls = smtp_use_tls
 
-################################################################################
-## WARNING: *DEBUG MODE MUST BE OFF IN A PRODUCTION ENVIRONMENT*              ##
-## Debug mode will enable the interactive debugging tool, allowing ANYONE to  ##
-## execute malicious code after an exception is raised.                       ##
-################################################################################
-#debug = false
-debug = true
 
 ##################################
 ###       LOGVIEW CONFIG       ###
diff -r 238885eaead4 -r 4869a8bb1237 docs/contributing.rst
--- a/docs/contributing.rst	Wed Apr 22 20:53:22 2020 +0200
+++ b/docs/contributing.rst	Wed Apr 22 20:47:02 2020 +0200
@@ -266,6 +266,20 @@
 a freshly created model object (before flushing, the ID attribute will
 be ``None``).
 
+Debugging
+^^^^^^^^^
+
+A good way to trace what Kallithea is doing is to keep an eye on the output of
+stdout/stderr from the server process. Perhaps change ``my.ini`` to log at
+``DEBUG`` or ``INFO`` level, especially ``[logger_kallithea]``, but perhaps
+also other loggers. It is often easier to add additional ``log`` or ``print``
+statements than to use a Python debugger.
+
+Sometimes it is simpler to disable ``errorpage.enabled`` and perhaps also
+``trace_errors.enable`` to expose raw errors instead of adding extra
+processing. Enabling ``debug`` can be helpful for showing and exploring
+tracebacks in the browser, but is also insecure and will add extra processing.
+
 TurboGears2 DebugBar
 ^^^^^^^^^^^^^^^^^^^^
 
diff -r 238885eaead4 -r 4869a8bb1237 kallithea/lib/paster_commands/template.ini.mako
--- a/kallithea/lib/paster_commands/template.ini.mako	Wed Apr 22 20:53:22 2020 +0200
+++ b/kallithea/lib/paster_commands/template.ini.mako	Wed Apr 22 20:47:02 2020 +0200
@@ -391,9 +391,21 @@
 #session.sa.url = postgresql://postgres:qwe@localhost/kallithea
 #session.table_name = db_session
 
-<%text>############################</%text>
-<%text>## ERROR HANDLING SYSTEMS ##</%text>
-<%text>############################</%text>
+<%text>####################################</%text>
+<%text>###       ERROR HANDLING        ####</%text>
+<%text>####################################</%text>
+
+<%text>## Show a nice error page for application HTTP errors and exceptions (default true)</%text>
+#errorpage.enabled = true
+
+<%text>## Enable Backlash client-side interactive debugger (default false)</%text>
+<%text>## WARNING: *THIS MUST BE false IN PRODUCTION ENVIRONMENTS!!!*</%text>
+<%text>## This debug mode will allow all visitors to execute malicious code.</%text>
+#debug = false
+
+<%text>## Enable Backlash server-side error reporting (unless debug mode handles it client-side) (default true)</%text>
+#trace_errors.enable = true
+<%text>## Errors will be reported by mail if trace_errors.error_email is set.</%text>
 
 <%text>## Propagate email settings to ErrorReporter of TurboGears2</%text>
 <%text>## You do not normally need to change these lines</%text>
@@ -481,12 +493,6 @@
 sentry.exclude_paths =
 
 %endif
-<%text>################################################################################</%text>
-<%text>## WARNING: *DEBUG MODE MUST BE OFF IN A PRODUCTION ENVIRONMENT*              ##</%text>
-<%text>## Debug mode will enable the interactive debugging tool, allowing ANYONE to  ##</%text>
-<%text>## execute malicious code after an exception is raised.                       ##</%text>
-<%text>################################################################################</%text>
-debug = false
 
 <%text>##################################</%text>
 <%text>###       LOGVIEW CONFIG       ###</%text>