Docs: Enhance deployment guides, tutorial warnings and API examples

docs/api.rst

@@ -336,14 +336,14 @@ Signals are provided by the `Blinker`_ library. See :doc:`signals` for an introd
 
    Example subscriber::
 
+        from flask import template_rendered
+
+        @template_rendered.connect_via(app)
         def log_template_renders(sender, template, context, **extra):
             sender.logger.debug('Rendering template "%s" with context %s',
                                 template.name or 'string template',
                                 context)
 
-        from flask import template_rendered
-        template_rendered.connect(log_template_renders, app)
-
 .. data:: flask.before_render_template
    :noindex:
 
@@ -370,12 +370,12 @@ Signals are provided by the `Blinker`_ library. See :doc:`signals` for an introd
 
    Example subscriber::
 
+        from flask import request_started
+
+        @request_started.connect_via(app)
         def log_request(sender, **extra):
             sender.logger.debug('Request context is set up')
 
-        from flask import request_started
-        request_started.connect(log_request, app)
-
 .. data:: request_finished
 
    This signal is sent right before the response is sent to the client.

docs/deploying/gunicorn.rst

@@ -71,6 +71,41 @@ errors are shown. To show access logs on stdout, use the
 ``--access-logfile=-`` option.
 
 
+Configuration File
+------------------
+
+While passing arguments to Gunicorn via the command line is useful for simple
+setups, production deployments usually rely on a configuration file.
+
+Create a file named ``gunicorn.conf.py`` in your project directory:
+
+.. code-block:: python
+
+    # gunicorn.conf.py
+    bind = "127.0.0.1:8000"
+    workers = 4
+    accesslog = "-"
+
+You can then run Gunicorn by pointing it to your configuration file using
+the ``-c`` option:
+
+.. code-block:: text
+
+    $ gunicorn -c gunicorn.conf.py 'example:app'
+
+
+Running in the Background
+-------------------------
+
+Running Gunicorn from the command line blocks the terminal. For production
+deployments, you should use a process manager like ``systemd`` or ``supervisor``
+to run Gunicorn in the background, start it automatically on boot and restart
+it if it crashes.
+
+See the Gunicorn documentation on `Deploying Gunicorn <https://docs.gunicorn.org/en/latest/deploy.html>`_
+for examples of systemd service files.
+
+
 Binding Externally
 ------------------
 
@@ -92,6 +127,13 @@ otherwise it will be possible to bypass the proxy.
 ``0.0.0.0`` is not a valid address to navigate to, you'd use a specific
 IP address in your browser.
 
+.. note::
+    When running Gunicorn behind a reverse proxy, the proxy will intercept the
+    client's IP address. To ensure your Flask application correctly reads the
+    forwarded headers (like ``X-Forwarded-For``), you must apply the
+    :class:`~werkzeug.middleware.proxy_fix.ProxyFix` middleware. See
+    :doc:`proxy_fix` for more information.
+
 
 Async with gevent
 -----------------

docs/tutorial/database.rst

@@ -206,6 +206,14 @@ previous page.
     you use a new terminal, remember to change to your project directory
     and activate the env as described in :doc:`/installation`.
 
+.. warning::
+
+    The ``init-db`` command will run the ``schema.sql`` file, which starts by
+    dropping the existing ``user`` and ``post`` tables. **Running this command
+    will permanently delete any existing data in your database.** Only run it
+    when you are setting up the project for the first time or if you intentionally
+    want to start over with an empty database.
+
 Run the ``init-db`` command:
 
 .. code-block:: none

docs/tutorial/deploy.rst

@@ -39,9 +39,9 @@ Pip will install your project along with its dependencies.
 Since this is a different machine, you need to run ``init-db`` again to
 create the database in the instance folder.
 
-    .. code-block:: text
+.. code-block:: text
 
-        $ flask --app flaskr init-db
+    $ flask --app flaskr init-db
 
 When Flask detects that it's installed (not in editable mode), it uses
 a different directory for the instance folder. You can find it at
@@ -72,6 +72,12 @@ will read from if it exists. Copy the generated value into it.
 
     SECRET_KEY = '192b9bdd22ab9ed4d12e236c78afcb9a393ec15f71bbf5dc987d54727823bcbf'
 
+.. warning::
+    Never commit the file containing your production ``SECRET_KEY`` to version
+    control. Ensure that your ``.gitignore`` file excludes the ``instance/``
+    folder and the specific ``config.py`` file to prevent leaking your secret
+    key to a public repository.
+
 You can also set any other necessary configuration here, although
 ``SECRET_KEY`` is the only one needed for Flaskr.