implement maintenance mode

2 files changed, 71 insertions, 0 deletions

diff --git a/doc/administration.rst b/doc/administration.rst
index 706a4cb..6cf0f52 100644
--- a/doc/administration.rst
+++ b/doc/administration.rst
@@ -11,6 +11,7 @@ Administration Guide
     administration/backup
     administration/cronjobs
     administration/custom-pages
+    administration/maintenance-mode
 
 This guide contains information pertaining to the administration of a Fietsboek
 instance. This includes the installation, updating, configuration, and backing
diff --git a/doc/administration/maintenance-mode.rst b/doc/administration/maintenance-mode.rst
new file mode 100644
index 0000000..d02e27a
--- /dev/null
+++ b/doc/administration/maintenance-mode.rst
@@ -0,0 +1,70 @@
+Maintenance Mode
+================
+
+Sometimes, it can be useful to deactivate your fietsboek instance temporarily,
+for example when you want to apply updates, or you need to otherwise fiddle
+with the data. Deactivating your instance avoids any "race issues" or accesses
+to the database and such, which might be in inconsistent states.
+
+To help with this situation, fietsboek provides a *maintenance mode*. This
+allows you to deactivate fietsboek without having to fiddle with your webserver
+settings.
+
+In the maintenance mode, fietsboek will reply to any HTTP request with a ``503
+Service Unavailable`` response, and won't process the requests further.
+
+.. note::
+
+    The maintenance mode is implemented early in fietsboek, however if you have
+    custom HTTP proxies or other WSGI middleware between fietsboek and the
+    outside world, the maintenance mode will not affect those.
+
+    In those cases, it might be better to deactivate the whole pipeline,
+    depending on the setup and the middleware used — at least if those also
+    access the database.
+
+In addition to not replying to HTTP requests, ``fietscron`` will also respect
+the maintenance mode and do nothing. This is to avoid accidental interference
+with long tasks like updating, such that a cronjob doesn't access data in an
+invalid state.
+
+Unlike ``fietscron`` and the HTTP requests, ``fietsctl`` and ``fietsupdate``
+will **continue to work**.
+
+Controlling the Maintenance Mode
+--------------------------------
+
+You can enable and disable the maintenance mode using the ``fietsctl`` script.
+To enable the mode, simply pass a reason (that will be shown to users) to
+``fietsctl maintenance-mode``::
+
+    fietsctl -c production.ini maintenance-mode "Updating the instance"
+
+Similarly, you can disable the maintenance mode by passing the ``--disable``
+flag::
+
+    fietsctl -c production.ini maintenance-mode --disable
+
+To check the current status of the maintenance mode, call the subcommand
+without extra arguments::
+
+    fietsctl -c production.ini maintenance-mode
+
+Manually Intervening with Maintenance
+-------------------------------------
+
+If you cannot (or don't want to) use the ``fietsctl maintenance-mode`` command,
+you can also manually control the maintenance mode: The :file:`MAINTENANCE`
+file in the data directory controls whether the mode is enabled or disabled.
+
+To enable the maintenance mode, it is enough to ensure that the file exists::
+
+    touch data-dir/MAINTENANCE
+
+The reason for the maintenance mode is saved in the file content::
+
+    echo "Updating the instance" > data-dir/MAINTENANCE
+
+To disable the maintenance mode, remove the file again::
+
+    rm data-dir/MAINTENANCE