docs: add deployment section for nginx-unit

docs/examples/deployment/nginx-unit/install-macos.sh

@@ -0,0 +1,2 @@
+brew install unit-python311
+brew install nginx/unit/unit-python3

docs/examples/deployment/nginx-unit/unit.json

@@ -0,0 +1,20 @@
+{
+  "listeners": {
+    "*:8080": {
+      "pass": "applications/litestar"
+    }
+  },
+
+  "applications": {
+    "litestar": {
+      "type": "python 3.11",
+      "home": "/Users/user/project/listestar/.venv/",
+      "path": "/Users/user/project/litestar/src/app",
+      "module": "run",
+      "callable": "app",
+      "stderr": "/Users/user/project/litestar/error.log",
+      "user": "user",
+      "processes": 1
+    }
+  }
+}

docs/topics/deployment/index.rst

@@ -0,0 +1,10 @@
+Deployment
+==========
+
+
+Contents
+--------
+
+.. toctree::
+
+    nginx-unit

docs/topics/deployment/nginx-unit.rst

@@ -0,0 +1,98 @@
+NGINX Unit
+==========
+
+To run litestar using `nginx-unit <https://unit.nginx.org/>`_
+
+Install nginx-unit
+------------------
+
+To install ``nginx-unit``, refer to the `official documentation <https://unit.nginx.org/installation/>`_
+
+.. tab-set::
+
+   .. tab-item:: macOS (`Brew <https://brew.sh/>`_)
+
+        .. literalinclude:: /examples/deployment/nginx-unit/install-macos.sh
+            :language: sh
+
+   .. tab-item:: Ubuntu
+
+        To be done
+
+
+Start the process, replace `user` by your system user.
+
+.. code-block:: sh
+
+    unitd --user <user>
+
+
+3. Create a `run.py` file containing the reference of your litestar app
+
+.. literalinclude:: /examples/todo_app/hello_world.py
+    :language: python
+    :caption: run.py
+
+
+Configuration
+-------------
+
+Create a file called `unit.json`, put it at the root of the your project
+
+.. literalinclude:: /examples/deployment/nginx-unit/unit.json
+    :language: json
+    :caption: unit.json
+
+Listeners
++++++++++
+
+To accept requests, add a listener object in the config/listeners API section; the object’s name can be:
+
+- A unique IP socket: ``127.0.0.1:80``, ``[::1]:8080``
+- A wildcard that matches any host IPs on the port: ``*:80``
+- On Linux-based systems, abstract UNIX sockets can be used as well: ``unix:@abstract_socket``.
+
+
+Applications
+++++++++++++
+
+Each app that Unit runs is defined as an object in the ``/config/applications`` section of the control API; it lists the app’s language and settings, its runtime limits, process model, and various language-specific options.
+
++------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+| Option                 | Value             | Description                                                                                                                                        |
++------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``type`` (required)    | `python 3.12`     | Application type: `python` ``"type": "python 3"``, ``"type": "python 3.12"``                                                                       |
+|                        |                   |                                                                                                                                                    |
+|                        |                   | Unit searches its modules and uses the latest matching one, reporting an error if none match.                                                      |
++------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``home``               | `venv`            | String; path to the app’s virtual environment. Absolute or relative to ``working_directory``.                                                      |
++------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``path``               | `src/app`         | String or an array of strings; additional Python module lookup paths. These values are prepended to ``sys.path``.                                  |
++------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``module`` (required)  | `run`             | String; app’s module name. This module is imported by Unit the usual Python way.                                                                   |
++------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``callable``           | `app`             | String; name of the module-based callable that Unit runs as the app. The default is `application`.                                                 |
++------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``working_directory``  | <path_to_project> | String; the app’s working directory. The default is the working directory of Unit’s main process.                                                  |
++------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``stderr``, ``stdout`` | `log_error.log`   | Strings; filenames where Unit redirects the application’s output.                                                                                  |
+|                        |                   |                                                                                                                                                    |
+|                        |                   | The default is ``/dev/null``.                                                                                                                      |
++------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``user``               |                   | String; username that runs the app process.                                                                                                        |
++------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``group``              |                   | String; group name that runs the app process. The default is the ``user``’s primary group.                                                         |
++------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``processes``          | 1                 | Integer or object; integer sets a static number of app processes, and object options `max`, `spare`, and `idle_timeout` enable dynamic management. |
+|                        |                   |                                                                                                                                                    |
+|                        |                   | The default is 1.                                                                                                                                  |
++------------------------+-------------------+----------------------------------------------------------------------------------------------------------------------------------------------------+
+
+Configuration update
+--------------------
+
+To update the nginx-unit service already running, use ``PUT`` method to send the ``unit.json`` file on the ``/config`` endpoint
+
+.. code-block:: sh
+
+    curl -X PUT --data-binary @unit.json --unix-socket /opt/homebrew/var/run/unit/control.sock http://localhost/config

docs/topics/index.rst

@@ -8,3 +8,4 @@ design decisions and similar topics on a higher level.
 .. toctree::
 
     sync-vs-async
+    deployment/index