diff --git a/docs/blueprints.rst b/docs/blueprints.rst index 0a38a530..dbad7826 100644 --- a/docs/blueprints.rst +++ b/docs/blueprints.rst @@ -242,7 +242,6 @@ you can use relative redirects by prefixing the endpoint with a dot only:: This will link to ``admin.index`` for instance in case the current request was dispatched to any other admin blueprint endpoint. -.. _my-blueprint-error-label: Blueprint Error Handlers ------------------------ diff --git a/docs/debugging.rst b/docs/debugging.rst new file mode 100644 index 00000000..8370d624 --- /dev/null +++ b/docs/debugging.rst @@ -0,0 +1,97 @@ +Debugging Application Errors +============================ + + +In Production +------------- + +**Do not run the development server, or enable the built-in debugger, in +a production environment.** The debugger allows executing arbitrary +Python code from the browser. It's protected by a pin, but that should +not be relied on for security. + +Use an error logging tool, such as Sentry, as described in +:ref:`error-logging-tools`, or enable logging and notifications as +described in :doc:`/logging`. + +If you have access to the server, you could add some code to start an +external debugger if ``request.remote_addr`` matches your IP. Some IDE +debuggers also have a remote mode so breakpoints on the server can be +interacted with locally. Only enable a debugger temporarily. + + +The Built-In Debugger +--------------------- + +The built-in Werkzeug development server provides a debugger which shows +an interactive traceback in the browser when an unhandled error occurs +during a request. This debugger should only be used during development. + +.. image:: _static/debugger.png + :align: center + :class: screenshot + :alt: screenshot of debugger in action + +.. warning:: + + The debugger allows executing arbitrary Python code from the + browser. It is protected by a pin, but still represents a major + security risk. Do not run the development server or debugger in a + production environment. + +To enable the debugger, run the development server with the +``FLASK_ENV`` environment variable set to ``development``. This puts +Flask in debug mode, which changes how it handles some errors, and +enables the debugger and reloader. + +.. code-block:: text + + $ export FLASK_ENV=development + $ flask run + +``FLASK_ENV`` can only be set as an environment variable. When running +from Python code, passing ``debug=True`` enables debug mode, which is +mostly equivalent. Debug mode can be controled separately from +``FLASK_ENV`` with the ``FLASK_DEBUG`` environment variable as well. + +.. code-block:: python + + app.run(debug=True) + +:doc:`/server` and :doc:`/cli` have more information about running the +debugger, debug mode, and development mode. More information about the +debugger can be found in the `Werkzeug documentation +`__. + + +External Debuggers +------------------ + +External debuggers, such as those provided by IDEs, can offer a more +powerful debugging experience than the built-in debugger. They can also +be used to step through code during a request before an error is raised, +or if no error is raised. Some even have a remote mode so you can debug +code running on another machine. + +When using an external debugger, the app should still be in debug mode, +but it can be useful to disable the built-in debugger and reloader, +which can interfere. + +When running from the command line: + +.. code-block:: text + + $ export FLASK_ENV=development + $ flask run --no-debugger --no-reload + +When running from Python: + +.. code-block:: python + + app.run(debug=True, use_debugger=False, use_reloader=False) + +Disabling these isn't required, an external debugger will continue to +work with the following caveats. If the built-in debugger is not +disabled, it will catch unhandled exceptions before the external +debugger can. If the reloader is not disabled, it could cause an +unexpected reload if code changes during debugging. diff --git a/docs/errorhandling.rst b/docs/errorhandling.rst index 5d1dbf3b..7f21f58f 100644 --- a/docs/errorhandling.rst +++ b/docs/errorhandling.rst @@ -73,8 +73,6 @@ See also: - `Flask-specific documentation `__ -.. _error-handlers: - Error Handlers -------------- @@ -529,63 +527,12 @@ parameter. Logging ------- -See :doc:`/logging` for information on how to log exceptions, such as by -emailing them to admins. - -Debugging Application Errors -============================ - -For production applications, configure your application with logging and -notifications as described in :doc:`/logging`. This section provides -pointers when debugging deployment configuration and digging deeper with a -full-featured Python debugger. - -When in Doubt, Run Manually ---------------------------- - -Having problems getting your application configured for production? If you -have shell access to your host, verify that you can run your application -manually from the shell in the deployment environment. Be sure to run under -the same user account as the configured deployment to troubleshoot permission -issues. You can use Flask's builtin development server with `debug=True` on -your production host, which is helpful in catching configuration issues, but -**be sure to do this temporarily in a controlled environment.** Do not run in -production with `debug=True`. +See :doc:`/logging` for information about how to log exceptions, such as +by emailing them to admins. -.. _working-with-debuggers: +Debugging +--------- -Working with Debuggers ----------------------- - -The built-in development server provides a :ref:`debug-mode` that shows -an interactive traceback in the browser when an unhandled error occurs -during a request. - -External debuggers, such as those provided by IDEs, can offer a much -more powerful and visual debugging experience. They can also be used to -step through code during a request before an error is raised, or if no -error is raised. - -When using an external debugger, the app should still be in debug mode, -but it can be useful to disable the built-in debugger and reloader, -which can interfere. - -When running from the command line: - -.. code-block:: text - - $ export FLASK_ENV=development - $ flask run --no-debugger --no-reload - -When running from Python: - -.. code-block:: python - - app.run(debug=True, use_debugger=False, use_reloader=False) - -Disabling these isn't required, an external debugger will continue to -work with the following caveats. If the built-in debugger is not -disabled, it will catch unhandled exceptions before the external -debugger can. If the reloader is not disabled, it could cause an -unexpected reload if code changes during debugging. +See :doc:`/debugging` for information about how to debug errors in +development and production. diff --git a/docs/index.rst b/docs/index.rst index eef180d6..ec47b232 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,6 +44,7 @@ instructions for web development with Flask. templating testing errorhandling + debugging logging config signals diff --git a/docs/quickstart.rst b/docs/quickstart.rst index b3028998..7a0e8cea 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -111,59 +111,43 @@ application). It will tell you what it tried to import and why it failed. The most common reason is a typo or because you did not actually create an ``app`` object. -.. _debug-mode: Debug Mode ---------- -(Want to just log errors and stack traces? See :doc:`errorhandling`) +The ``flask run`` command can do more than just start the development +server. By enabling debug mode, the server will automatically reload if +code changes, and will show an interactive debugger in the browser if an +error occurs during a request. -The :command:`flask` script is nice to start a local development server, but -you would have to restart it manually after each change to your code. -That is not very nice and Flask can do better. If you enable debug -support the server will reload itself on code changes, and it will also -provide you with a helpful debugger if things go wrong. +.. image:: _static/debugger.png + :align: center + :class: screenshot + :alt: The interactive debugger in action. -To enable all development features (including debug mode) you can export -the ``FLASK_ENV`` environment variable and set it to ``development`` -before running the server:: +.. warning:: + + The debugger allows executing arbitrary Python code from the + browser. It is protected by a pin, but still represents a major + security risk. Do not run the development server or debugger in a + production environment. + +To enable all development features, set the ``FLASK_ENV`` environment +variable to ``development`` before calling ``flask run``. + +.. code-block:: text $ export FLASK_ENV=development $ flask run -(On Windows you need to use ``set`` instead of ``export``.) +See also: -This does the following things: - -1. it activates the debugger -2. it activates the automatic reloader -3. it enables the debug mode on the Flask application. - -You can also control debug mode separately from the environment by -exporting ``FLASK_DEBUG=1``. - -There are more parameters that are explained in :doc:`/server`. - -.. admonition:: Attention - - Even though the interactive debugger does not work in forking environments - (which makes it nearly impossible to use on production servers), it still - allows the execution of arbitrary code. This makes it a major security risk - and therefore it **must never be used on production machines**. - -Screenshot of the debugger in action: - -.. image:: _static/debugger.png - :align: center - :class: screenshot - :alt: screenshot of debugger in action - -More information on using the debugger can be found in the `Werkzeug -documentation`_. - -.. _Werkzeug documentation: https://werkzeug.palletsprojects.com/debug/#using-the-debugger - -Have another debugger in mind? See :ref:`working-with-debuggers`. +- :doc:`/server` and :doc:`/cli` for information about running in + development mode. +- :doc:`/debugging` for information about using the built-in debugger + and other debuggers. +- :doc:`/logging` and :doc:`/errorhandling` to log errors and display + nice error pages. HTML Escaping