diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index c1e15699..229f4b4a 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.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.] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 581f17e3..4c59fb02 100644 --- a/CONTRIBUTING.md +++ b/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) diff --git a/docs/configuration/config_yaml.rst b/docs/configuration/config_yaml.rst index 9670645a..c48389ae 100644 --- a/docs/configuration/config_yaml.rst +++ b/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 diff --git a/docs/features/index.rst b/docs/features/index.rst index 4d1b9f1f..ebbf4882 100644 --- a/docs/features/index.rst +++ b/docs/features/index.rst @@ -16,3 +16,4 @@ Features gcode_scripts.rst action_commands.rst plugins.rst + safemode.rst diff --git a/docs/features/plugins.rst b/docs/features/plugins.rst index 1b65b6dc..2530f781 100644 --- a/docs/features/plugins.rst +++ b/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-plugins-available: Finding Plugins diff --git a/docs/features/safemode.rst b/docs/features/safemode.rst new file mode 100644 index 00000000..19e4150b --- /dev/null +++ b/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 ` + 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 diff --git a/docs/images/features-safemode-notification.png b/docs/images/features-safemode-notification.png new file mode 100644 index 00000000..4cdaa5f4 Binary files /dev/null and b/docs/images/features-safemode-notification.png differ diff --git a/docs/images/features-safemode-systemmenu.png b/docs/images/features-safemode-systemmenu.png new file mode 100644 index 00000000..3bbafa15 Binary files /dev/null and b/docs/images/features-safemode-systemmenu.png differ