From 5ebb71a6552be7925743a5ba5ff2394ee88378d1 Mon Sep 17 00:00:00 2001 From: Julien Date: Sat, 4 Nov 2023 09:40:04 +0100 Subject: [PATCH 1/8] docs: add nginx unit section --- .../deployment/nginx-unit/install-macos.sh | 2 + docs/examples/deployment/nginx-unit/unit.json | 20 ++++ docs/usage/deployment/index.rst | 10 ++ docs/usage/deployment/nginx-unit.rst | 98 +++++++++++++++++++ docs/usage/index.rst | 1 + 5 files changed, 131 insertions(+) create mode 100644 docs/examples/deployment/nginx-unit/install-macos.sh create mode 100644 docs/examples/deployment/nginx-unit/unit.json create mode 100644 docs/usage/deployment/index.rst create mode 100644 docs/usage/deployment/nginx-unit.rst diff --git a/docs/examples/deployment/nginx-unit/install-macos.sh b/docs/examples/deployment/nginx-unit/install-macos.sh new file mode 100644 index 0000000000..bcacab5ad4 --- /dev/null +++ b/docs/examples/deployment/nginx-unit/install-macos.sh @@ -0,0 +1,2 @@ +brew install unit-python311 +brew install nginx/unit/unit-python3 \ No newline at end of file diff --git a/docs/examples/deployment/nginx-unit/unit.json b/docs/examples/deployment/nginx-unit/unit.json new file mode 100644 index 0000000000..1118e562e4 --- /dev/null +++ b/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 + } + } +} \ No newline at end of file diff --git a/docs/usage/deployment/index.rst b/docs/usage/deployment/index.rst new file mode 100644 index 0000000000..aa84f1c994 --- /dev/null +++ b/docs/usage/deployment/index.rst @@ -0,0 +1,10 @@ +Deployment +========== + + +Contents +-------- + +.. toctree:: + + nginx-unit diff --git a/docs/usage/deployment/nginx-unit.rst b/docs/usage/deployment/nginx-unit.rst new file mode 100644 index 0000000000..d0b3aab775 --- /dev/null +++ b/docs/usage/deployment/nginx-unit.rst @@ -0,0 +1,98 @@ +NGINX Unit +========== + +To run litestar using `nginx-unit `_ + +Install nginx-unit +------------------ + +1. To install nginx-unit, refers to the `offical documentation `_ + +.. tab-set:: + + .. tab-item:: macOS (Brew) + + .. 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 + + +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`` | | 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 diff --git a/docs/usage/index.rst b/docs/usage/index.rst index de7c2a3f2c..43499187e4 100644 --- a/docs/usage/index.rst +++ b/docs/usage/index.rst @@ -30,3 +30,4 @@ Usage cli testing debugging + deployment/index From f65a857cfc914d17daaeee11cd76858ca11c5caa Mon Sep 17 00:00:00 2001 From: Julien Date: Sat, 4 Nov 2023 09:54:13 +0100 Subject: [PATCH 2/8] docs: fix typo in nginx unit doc --- docs/examples/deployment/nginx-unit/install-macos.sh | 2 +- docs/examples/deployment/nginx-unit/unit.json | 2 +- docs/usage/deployment/nginx-unit.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/examples/deployment/nginx-unit/install-macos.sh b/docs/examples/deployment/nginx-unit/install-macos.sh index bcacab5ad4..dbd3250193 100644 --- a/docs/examples/deployment/nginx-unit/install-macos.sh +++ b/docs/examples/deployment/nginx-unit/install-macos.sh @@ -1,2 +1,2 @@ brew install unit-python311 -brew install nginx/unit/unit-python3 \ No newline at end of file +brew install nginx/unit/unit-python3 diff --git a/docs/examples/deployment/nginx-unit/unit.json b/docs/examples/deployment/nginx-unit/unit.json index 1118e562e4..cd2c93860a 100644 --- a/docs/examples/deployment/nginx-unit/unit.json +++ b/docs/examples/deployment/nginx-unit/unit.json @@ -17,4 +17,4 @@ "processes": 1 } } -} \ No newline at end of file +} diff --git a/docs/usage/deployment/nginx-unit.rst b/docs/usage/deployment/nginx-unit.rst index d0b3aab775..78cafe1d61 100644 --- a/docs/usage/deployment/nginx-unit.rst +++ b/docs/usage/deployment/nginx-unit.rst @@ -6,7 +6,7 @@ To run litestar using `nginx-unit `_ Install nginx-unit ------------------ -1. To install nginx-unit, refers to the `offical documentation `_ +1. To install nginx-unit, refers to the `official documentation `_ .. tab-set:: From 10951e7a58576a084ce58b6928ebb20c7ea505e0 Mon Sep 17 00:00:00 2001 From: Julien Date: Sat, 4 Nov 2023 09:59:02 +0100 Subject: [PATCH 3/8] docs: fix indent of example unit json file --- docs/examples/deployment/nginx-unit/unit.json | 32 +++++++++---------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/examples/deployment/nginx-unit/unit.json b/docs/examples/deployment/nginx-unit/unit.json index cd2c93860a..7623013d39 100644 --- a/docs/examples/deployment/nginx-unit/unit.json +++ b/docs/examples/deployment/nginx-unit/unit.json @@ -1,20 +1,20 @@ { - "listeners": { - "*:8080": { - "pass": "applications/litestar" - } - }, + "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 - } + "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 } + } } From adf551797a82e84223121b88f5cea3210d4df06b Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Sat, 4 Nov 2023 11:32:31 -0500 Subject: [PATCH 4/8] Update docs/usage/deployment/nginx-unit.rst --- docs/usage/deployment/nginx-unit.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/deployment/nginx-unit.rst b/docs/usage/deployment/nginx-unit.rst index 78cafe1d61..78deb4d1bc 100644 --- a/docs/usage/deployment/nginx-unit.rst +++ b/docs/usage/deployment/nginx-unit.rst @@ -6,7 +6,7 @@ To run litestar using `nginx-unit `_ Install nginx-unit ------------------ -1. To install nginx-unit, refers to the `official documentation `_ +To install ``nginx-unit``, refer to the `official documentation `_ .. tab-set:: From 2d597181e482db6ef26f89f9b77d39189f1e8583 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Sat, 4 Nov 2023 11:32:46 -0500 Subject: [PATCH 5/8] Update docs/usage/deployment/nginx-unit.rst --- docs/usage/deployment/nginx-unit.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/usage/deployment/nginx-unit.rst b/docs/usage/deployment/nginx-unit.rst index 78deb4d1bc..36ed225394 100644 --- a/docs/usage/deployment/nginx-unit.rst +++ b/docs/usage/deployment/nginx-unit.rst @@ -48,9 +48,9 @@ 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. +- 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 From d361245fd438cffc68224e2ca04a0965cfc1c27a Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Sat, 4 Nov 2023 11:32:52 -0500 Subject: [PATCH 6/8] Update docs/usage/deployment/nginx-unit.rst --- docs/usage/deployment/nginx-unit.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/deployment/nginx-unit.rst b/docs/usage/deployment/nginx-unit.rst index 36ed225394..8987510a04 100644 --- a/docs/usage/deployment/nginx-unit.rst +++ b/docs/usage/deployment/nginx-unit.rst @@ -91,7 +91,7 @@ Each app that Unit runs is defined as an object in the ``/config/applications`` Configuration update -------------------- -To update the nginx-unit service already running, use ``PUT`` method to send the ``unit.json`` file on the `/config` endpoint +To update the nginx-unit service already running, use ``PUT`` method to send the ``unit.json`` file on the ``/config`` endpoint .. code-block:: sh From c79d8aa76c14c375fb3520040739e8ca38b01b84 Mon Sep 17 00:00:00 2001 From: Jacob Coffee Date: Sat, 4 Nov 2023 11:33:04 -0500 Subject: [PATCH 7/8] Update docs/usage/deployment/nginx-unit.rst --- docs/usage/deployment/nginx-unit.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/deployment/nginx-unit.rst b/docs/usage/deployment/nginx-unit.rst index 8987510a04..2eab278e38 100644 --- a/docs/usage/deployment/nginx-unit.rst +++ b/docs/usage/deployment/nginx-unit.rst @@ -10,7 +10,7 @@ To install ``nginx-unit``, refer to the `official documentation `_) .. literalinclude:: /examples/deployment/nginx-unit/install-macos.sh :language: sh From 0aae7a08c540c28f75c927195392788ebd2fb51b Mon Sep 17 00:00:00 2001 From: Julien Date: Sat, 4 Nov 2023 20:10:33 +0100 Subject: [PATCH 8/8] docs: move deployment from usage to topics --- docs/{usage => topics}/deployment/index.rst | 0 docs/{usage => topics}/deployment/nginx-unit.rst | 0 docs/topics/index.rst | 1 + docs/usage/index.rst | 1 - 4 files changed, 1 insertion(+), 1 deletion(-) rename docs/{usage => topics}/deployment/index.rst (100%) rename docs/{usage => topics}/deployment/nginx-unit.rst (100%) diff --git a/docs/usage/deployment/index.rst b/docs/topics/deployment/index.rst similarity index 100% rename from docs/usage/deployment/index.rst rename to docs/topics/deployment/index.rst diff --git a/docs/usage/deployment/nginx-unit.rst b/docs/topics/deployment/nginx-unit.rst similarity index 100% rename from docs/usage/deployment/nginx-unit.rst rename to docs/topics/deployment/nginx-unit.rst diff --git a/docs/topics/index.rst b/docs/topics/index.rst index a633a7d3ec..7fa5557a59 100644 --- a/docs/topics/index.rst +++ b/docs/topics/index.rst @@ -8,3 +8,4 @@ design decisions and similar topics on a higher level. .. toctree:: sync-vs-async + deployment/index diff --git a/docs/usage/index.rst b/docs/usage/index.rst index 43499187e4..de7c2a3f2c 100644 --- a/docs/usage/index.rst +++ b/docs/usage/index.rst @@ -30,4 +30,3 @@ Usage cli testing debugging - deployment/index