NGINX Unit#

To run litestar using nginx-unit

Install nginx-unit#

To install nginx-unit, refer to the official documentation

macOS (Brew)

brew install unit-python311
brew install nginx/unit/unit-python3

Ubuntu

To be done

Start the process, replace user by your system user.

unitd --user <user>

Create a run.py file containing the reference of your litestar app

run.py#

from litestar import Litestar, get

@get("/")
async def hello_world() -> str:
    return "Hello, world!"

app = Litestar([hello_world])

Configuration#

Create a file called unit.json, put it at the root of the your project

unit.json#

{
  "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
    }
  }
}

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

curl -X PUT --data-binary @unit.json --unix-socket /opt/homebrew/var/run/unit/control.sock http://localhost/config