Documentation updated for safe mode feature

.github/ISSUE_TEMPLATE.md

@@ -15,10 +15,17 @@ for contributing" linked above, read it!), NOT here.
 Mark requests with a "[Request]" prefix in the title please. Fully fill
 out the bug reporting template for bug reports (if you don't know where
 to find some information - it's all described in the contribution
-guidelines linked up there in the big yellow box). Do not delete any
-lines from the template but those enclosed in [ and ] - and those please
-DO delete, they are only provided for your information and removing them
-makes your ticket more readable :)
+guidelines linked up there in the big yellow box).
+
+When reporting a bug do NOT delete any lines from the template but
+those enclosed in [ and ] - and those please DO delete, they are
+only provided for your information and removing them makes your
+ticket more readable :)
+
+Make sure any bug you want to repor tis still present with the CURRENT
+OctoPrint version and that it does not vanish when you start OctoPrint
+in safe mode - how to do that is also explained in the contribution
+guidelines linked up there in the big yellow box.
 
 Thank you!
 
@@ -30,28 +37,31 @@ by heart ;))
 
 #### What were you doing?
 
-[Please be as specific as possible here. The maintainers will need to
-reproduce your issue in order to fix it and that is not possible if they
-don't know what you did to get it to happen in the first place.
+[Please describe the steps to reproduce your issue. Be as specific as
+possible here. The maintainers will need to reproduce your issue in
+order to fix it and that is not possible if they don't know what you
+did to get it to happen in the first place.
 
 If you encountered a problem with specific files of any sorts, make sure
 to also include a link to a file with which to reproduce the problem.]
 
-#### What did you expect to happen?
-
-#### What happened instead?
+#### What did you expect to happen and what happened instead?
 
 #### Branch & Commit or Version of OctoPrint
 
 [Can be found in the lower left corner of the web interface. ALWAYS INCLUDE.]
 
+#### Operating System running OctoPrint
+
+[OctoPi, Linux, Windows, MacOS, something else? With version please.]
+
 #### Printer model & used firmware incl. version
 
 [If applicable, always include if unsure.]
 
 #### Browser and Version of Browser, Operating System running Browser
 
-[If applicable, always include if unsure.]
+[If applicable, always include if unsure or reporting UI issues.]
 
 #### Link to octoprint.log
 
@@ -60,7 +70,8 @@ to also include a link to a file with which to reproduce the problem.]
 #### Link to contents of terminal tab or serial.log
 
 [On gist.github.com or pastebin.com. If applicable, always include if unsure or
-reporting communication issues. Never truncate.
+reporting any kind of communication issues between OctoPrint and your printer.
+Never truncate.
 
 serial.log is usually not written due to performance reasons and must be
 enabled explicitly. Provide at the very least the FULL contents of your
@@ -72,7 +83,7 @@ a serial.log.]
 [On gist.github.com or pastebin.com or alternatively a screenshot. If applicable -
 always include if unsure or reporting UI issues.]
 
-#### Screenshot(s) showing the problem:
+#### Screenshot(s) or video(s) showing the problem:
 
 [If applicable. Always include if unsure or reporting UI issues.]
 

CONTRIBUTING.md

@@ -94,7 +94,12 @@ following section *completely* and also follow the instructions in the
 2. Please make sure to **test out the current version** of OctoPrint to see
    whether the problem you are encountering still exists, and **test without
    any non-bundled plugins enabled** to make sure it's not a misbehaving
-   plugin causing the issue at hand.
+   plugin causing the issue at hand. For that you can restart OctoPrint in
+   **safe mode**, either by selecting "Restart OctoPrint in safe mode" from
+   the "System" menu, or by starting OctoPrint from the command line with
+   `octoprint --safe`.
+
+
 
    If you are feeling up to it you might also want to try the current development
    version of OctoPrint (if you aren't already). Refer to the [FAQ](https://github.com/foosel/OctoPrint/wiki/FAQ)

docs/configuration/config_yaml.rst

@@ -829,10 +829,14 @@ Use the following settings to configure the server:
      # Use this option to define the port to which to bind the server, defaults to 5000
      port: 5000
 
-     # If this option is true, OctoPrint will show the First Run dialog and set it to false after that
-     # completes
+     # If this option is true, OctoPrint will show the First Run wizard and set the setting to
+     # false after that completes
      firstRun: false
 
+     # If this option is true, OctoPrint will enable safe mode on the next server start and
+     # reset the setting to false
+     startOnceInSafeMode: false
+
      # Secret key for encrypting cookies and such, randomly generated on first run
      secretKey: someSecretKey
 

docs/features/index.rst

@@ -16,3 +16,4 @@ Features
    gcode_scripts.rst
    action_commands.rst
    plugins.rst
+   safemode.rst

docs/features/plugins.rst

@@ -11,6 +11,16 @@ Right now plugins can be used to extend OctoPrint's web interface, to execute sp
 shutdown, to provide custom (API) endpoints or whole user interfaces with special functionality, to react to system
 events or progress reports or to add support for additional slicers. More plugin types are planned for the future.
 
+.. note::
+
+   Since a plugin might not function properly and cause issues that are hard to diagnose or outright disrupt server
+   functionality, you might want to be able to start OctoPrint without any third party plugins enabled. This is also
+   very important when reporting bugs in OctoPrint, to ensure that what you are observing is actually a bug in
+   OctoPrint and not in any of your installed third party plugins.
+
+   To do that, OctoPrint has a built-in safe mode that disables all plugins not shipped as part of OctoPrint. You can
+   read more on how to enable that :ref:`here <sec-features-safemode>`.
+
 .. _sec-features-plugins-available:
 
 Finding Plugins

docs/features/safemode.rst

@@ -0,0 +1,64 @@
+.. _sec-features-safemode:
+
+*********
+Safe mode
+*********
+
+With the advent of support for plugins in OctoPrint, it quickly became apparent that some of the bugs
+reported on OctoPrint's bug tracker were actually bugs with installed third party plugins instead of
+OctoPrint itself.
+
+To allow an easier identification of these cases, OctoPrint 1.3.0 introduced safe mode. Starting
+OctoPrint in safe mode disables all plugins that are not bundled with OctoPrint, allowing to easier
+identify most cases where a third party plugin is the culprit of an observed issue.
+
+Additionally, OctoPrint allows uninstalling plugins in this mode, allowing recovery from cases where
+a third party plugin causes the server to not start up or the web interface to not render or function
+correctly anymore.
+
+.. _sec-features-safemode-how:
+
+How to start OctoPrint in safe mode
+===================================
+
+There exist three ways to start OctoPrint in safe mode:
+
+  * since OctoPrint 1.3.2: by selecting "Restart OctoPrint in safe mode" from the "System" menu,
+    if the "Restart OctoPrint" server command has been correctly configured (see :numref:`fig-features-safemode-systemmenu`).
+  * by starting OctoPrint with the command line parameter ``--safe``, e.g. ``octoprint --safe``
+  * by setting the option ``server.startOnceInSafeMode`` in :ref:`config.yaml <sec-configuration-config_yaml>`
+    to ``true`` and restarting
+
+The last two options will have OctoPrint enable safe mode only for the next server start - once you
+restart OctoPrint again, safe mode will be disabled again.
+
+.. _fig-features-safemode-systemmenu:
+.. figure:: ../images/features-safemode-systemmenu.png
+   :align: center
+   :alt: "Restart OctoPrint in safe mode" in the "System" menu
+
+   "Restart OctoPrint in safe mode" in the "System" menu
+
+.. _sec-features-safemode-differences:
+
+Differences of safe mode vs normal operation mode
+=================================================
+
+When OctoPrint is running in safe mode the following changes to its normal operation mode apply:
+
+  * OctoPrint will not enable any of the installed third party plugins. OctoPrint considers all plugins third
+    party plugins that do not ship with OctoPrint's sources, so any plugins installed either via `pip` or
+    into OctoPrint's plugin folder at ``~/.octoprint/plugins`` (Linux), ``%APPDATA%/OctoPrint`` (Windows) and
+    ``~/Library/Application Support/OctoPrint`` (MacOS).
+  * OctoPrint will still allow to uninstall third party plugins through the built-in Plugin Manager.
+  * OctoPrint will still allow to disable (bundled) plugins that are still enabled.
+  * OctoPrint will not allow to enable third party plugins.
+  * OctoPrint's web interface will display a persistent notification to remind you that it is running in
+    safe mode.
+
+.. _fig-features-safemode-notification:
+.. figure:: ../images/features-safemode-notification.png
+   :align: center
+   :alt: Persistent safe mode notification
+
+   Persistent safe mode notification