NGINX Unit

nginx-unit is a dynamic web application server, designed to run applications in multiple languages, serve static files, and more.

Use When

Running your application with nginx-unit is preferable when you need to run your application in a production environment, with a high level of control over the process.

For detailed understanding and further information, refer to the official nginx-unit documentation.

Alternatives

• Manually with an ASGI server:

  Direct control by running the application with an ASGI server like Uvicorn, Hypercorn, Daphne, etc.

• systemd:

  A system and service manager, integrated into many Linux distributions for managing system processes.

  Note

  Official documentation coming soon

• Supervisor:

  A process control system that can be used to automatically start, stop and restart processes; includes a web UI.

• Docker:

  Ideal for containerized environments, offering isolation and scalability.

  Note

  You can deploy nginx-unit with Docker using the official NGINX image.

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.

Start nginx-unit

unitd --user <user>

3. 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/litestar/.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, 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

Update nginx-unit configuration

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