NGINX Unit#

To run litestar using nginx-unit

Install nginx-unit#

To install nginx-unit, refer to the official documentation

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

To be done

Start the process, replace user by your system user.

unitd --user <user>
  1. 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