2022-05-13 16:13:23 +00:00
# NGINX Unit
2024-03-09 17:58:23 +00:00
[![Project Status: Active – The project has reached a stable, usable state and is being actively developed. ](https://www.repostatus.org/badges/latest/active.svg )](https://www.repostatus.org/#active)
2024-03-09 17:35:30 +00:00
[![CI ](https://github.com/nginx/unit/actions/workflows/ci.yml/badge.svg )](https://github.com/nginx/unit/actions/workflows/ci.yml "GitHub workflow CI")
2024-06-03 20:57:51 +00:00
[![GitHub Discussions ](https://img.shields.io/badge/GitHub-discussions-009639 )](https://github.com/nginx/unit/discussions "GitHub Discussions")
2024-03-09 17:58:23 +00:00
2022-05-13 16:13:23 +00:00
## Universal Web App Server
2022-09-05 09:42:18 +00:00
![NGINX Unit Logo ](docs/unitlogo.svg )
2022-05-13 16:13:23 +00:00
NGINX Unit is a lightweight and versatile open-source server that has
2023-05-10 12:23:33 +00:00
two primary capabilities:
2022-05-13 16:13:23 +00:00
2023-01-18 15:29:33 +00:00
- serves static media assets,
- runs application code in seven languages.
2022-05-13 16:13:23 +00:00
2023-01-18 15:29:33 +00:00
Unit compresses several layers of the modern application stack into a potent,
coherent solution with a focus on performance, low latency, and scalability. It
is intended as a universal building block for any web architecture regardless
of its complexity, from enterprise-scale deployments to your pet's homepage.
2022-05-13 16:13:23 +00:00
2023-05-10 20:15:17 +00:00
Its native [RESTful JSON API ](#openapi-specification ) enables dynamic
2023-05-10 19:57:42 +00:00
updates with zero interruptions and flexible configuration, while its
out-of-the-box productivity reliably scales to production-grade workloads. We
achieve that with a complex, asynchronous, multithreading architecture
comprising multiple processes to ensure security and robustness while getting
the most out of today's computing platforms.
2022-05-13 16:13:23 +00:00
2024-05-15 21:58:50 +00:00
## Installation
2022-05-13 16:13:23 +00:00
2023-01-18 15:29:33 +00:00
### macOS
2022-05-13 16:13:23 +00:00
2024-05-15 21:58:50 +00:00
Run the following command to install both `unitd` (the Unit daemon) and `unitctl` (the control tool).
2022-05-13 16:13:23 +00:00
``` console
$ brew install nginx/unit/unit
```
For details and available language packages, see the
[docs ](https://unit.nginx.org/installation/#homebrew ).
### Docker
``` console
2024-04-18 03:43:48 +00:00
$ docker pull unit:< TAG >
2024-04-16 23:20:06 +00:00
$ mkdir /tmp/unit-control # customize as needed.
$ docker run -d \
--mount type=bind,src=/tmp/unit-control,dst=/var/run \
--mount type=bind,src=.,dst=/www \
--network host \
unit
2022-05-13 16:13:23 +00:00
```
For a description of image tags, see the
[docs ](https://unit.nginx.org/installation/#docker-images ).
2024-04-22 23:58:47 +00:00
WARNING: latest image tag may not provide support for specific language
modules, *do* check the available image tags from the link above before
pulling your image.
2022-05-13 16:13:23 +00:00
2024-04-16 23:20:06 +00:00
Your current working directory will now be mounted to the Unit image at `/www` .
2024-04-22 23:58:47 +00:00
You can reach its socket at `/tmp/unit-control/control.unit.sock` assuming no
2024-04-16 23:20:06 +00:00
further customizations have been made.
2024-05-15 21:58:50 +00:00
### Debian, Ubuntu, Amazon Linux, Fedora, Red Hat
2022-05-13 16:13:23 +00:00
2024-05-15 21:58:50 +00:00
This helper script configures the correct package repositories for system.
2022-05-13 16:13:23 +00:00
``` console
2022-12-14 21:17:01 +00:00
$ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit & & chmod +x setup-unit
2024-05-15 21:58:50 +00:00
# ./setup-unit repo-config
```
Debian derivatives:
``` console
# apt install unit
```
Fedora derivatives:
``` console
# yum install unit
2022-05-13 16:13:23 +00:00
```
For details and available language packages, see the
[docs ](https://unit.nginx.org/installation/#official-packages ).
2024-05-15 21:58:50 +00:00
## Getting Started with `unitctl`
2022-05-13 16:13:23 +00:00
2024-05-15 21:58:50 +00:00
[`unitctl` ](tools/README.md ) streamlines the management of NGINX Unit processes
through an easy-to-use command line interface. To get started with `unitctl` ,
download it from the
[official GitHub releases ](https://github.com/nginx/unit/releases )
or [Homebrew ](#macos ).
### Installation
> [!NOTE]
> If you installed Unit with [Homebrew](#macos), you can skip this step
> as `unitctl` is included by default.
Download the appropriate `unitctl` binary for your system from the
[NGINX Unit releases ](https://github.com/nginx/unit/releases/ ).
2022-05-13 16:13:23 +00:00
``` console
2024-05-15 21:58:50 +00:00
$ tar xzvf unitctl-master-x86_64-unknown-linux-gnu.tar.gz
# mv unitctl /usr/local/bin/
2022-05-13 16:13:23 +00:00
```
2024-05-15 21:58:50 +00:00
## Launch Unit using Docker
If you have [Docker installed ](https://docs.docker.com/engine/install/ ) on
your machine, and then you can effortlessly spin up one of
[Unit's official Docker images ](https://hub.docker.com/_/unit )
alongside your application.
2024-04-16 23:20:06 +00:00
2024-05-15 21:58:50 +00:00
> [!TIP]
> How-to and configuration guides are available on
[unit.nginx.org ](https://unit.nginx.org/howto/ ) for web application frameworks
built with Python, PHP, WebAssembly, Node.js, Ruby, and more.
2024-04-16 23:20:06 +00:00
2024-05-15 21:58:50 +00:00
Here's an example using the `unit:python` Docker image:
``` console
$ unitctl instances new 127.0.0.1:8001 /path/to/app 'unit:python'
```
2024-04-16 23:20:06 +00:00
2024-05-15 21:58:50 +00:00
`/path/to/app` will mount to `/www` in the Docker filesystem.
2022-05-13 16:13:23 +00:00
2024-05-15 21:58:50 +00:00
Save this to `/path/to/app/wsgi.py` :
```python
def application(environ, start_response):
start_response("200 OK", [("Content-Type", "text/plain")])
return (b"Hello, Python on Unit!")
```
You can then interactively edit the currently active configuration:
``` console
$ unitctl edit
```
```jsonc
{
"listeners": {
"*:8000": {
// Point listener to new application
"pass": "applications/python"
}
},
// Add an application definition
"applications": {
"python": {
"type": "python",
"path": "/www/",
"module": "wsgi"
}
}
}
```
Valid configurations will be applied upon save and close.
``` console
$ curl localhost:8000
Hello, Python on Unit!
```
More Python configuration examples can be found in the
[Unit docs ](https://unit.nginx.org/howto/samples/#python ).
## Hello World with PHP and curl
2022-05-13 16:13:23 +00:00
2023-07-25 08:45:04 +00:00
Unit runs apps in a
[variety of languages ](https://unit.nginx.org/howto/samples/ ).
2024-05-15 21:58:50 +00:00
Let's explore the configuration of a simple PHP app on Unit with `curl` .
2023-07-25 08:45:04 +00:00
2022-05-13 16:13:23 +00:00
Suppose you saved a PHP script as `/www/helloworld/index.php` :
``` php
<?php echo "Hello, PHP on Unit!"; ?>
```
To run it on Unit with the `unit-php` module installed, first set up an
application object. Let's store our first config snippet in a file called
`config.json` :
``` json
{
"helloworld": {
"type": "php",
"root": "/www/helloworld/"
}
}
```
Saving it as a file isn't necessary, but can come in handy with larger objects.
2022-10-06 11:47:47 +00:00
Now, `PUT` it into the `/config/applications` section of Unit's control API,
2022-05-13 16:13:23 +00:00
usually available by default via a Unix domain socket:
``` console
# curl -X PUT --data-binary @config.json --unix-socket \
/path/to/control.unit.sock http://localhost/config/applications
```
``` json
{
"success": "Reconfiguration done."
}
```
2022-10-06 11:47:47 +00:00
Next, reference the app from a listener object in the `/config/listeners`
2022-05-13 16:13:23 +00:00
section of the API. This time, we pass the config snippet straight from the
command line:
``` console
2023-11-08 11:27:44 +00:00
# curl -X PUT -d '{"127.0.0.1:8080": {"pass": "applications/helloworld"}}' \
2022-05-13 16:13:23 +00:00
--unix-socket /path/to/control.unit.sock http://localhost/config/listeners
```
``` json
{
"success": "Reconfiguration done."
}
```
Now Unit accepts requests at the specified IP and port, passing them to the
application process. Your app works!
``` console
$ curl 127.0.0.1:8080
Hello, PHP on Unit!
```
Finally, query the entire `/config` section of the control API:
``` console
# curl --unix-socket /path/to/control.unit.sock http://localhost/config/
```
Unit's output should contain both snippets, neatly organized:
``` json
{
"listeners": {
"127.0.0.1:8080": {
"pass": "applications/helloworld"
}
},
"applications": {
"helloworld": {
"type": "php",
"root": "/www/helloworld/"
}
}
}
```
2024-04-16 23:20:06 +00:00
## WebAssembly
Unit supports running WebAssembly Components (WASI 0.2).
For more information see the
[Unit Configuration Docs ](https://unit.nginx.org/configuration/#configuration-wasm ).
2022-05-13 16:13:23 +00:00
2023-05-10 19:57:42 +00:00
## OpenAPI Specification
2023-05-10 20:15:17 +00:00
Our [OpenAPI specification ](docs/unit-openapi.yaml ) aims to simplify
configuring and integrating NGINX Unit deployments and provide an authoritative
source of knowledge about the control API.
2023-05-10 19:57:42 +00:00
2022-05-13 16:13:23 +00:00
## Community
- The go-to place to start asking questions and share your thoughts is
2024-01-09 15:32:17 +00:00
[GitHub Discussions ](https://github.com/nginx/unit/discussions ).
2022-05-13 16:13:23 +00:00
- Our [GitHub issues page ](https://github.com/nginx/unit/issues ) offers
space for a more technical discussion at your own pace.
- The [project map ](https://github.com/orgs/nginx/projects/1 ) on
GitHub sheds some light on our current work and plans for the future.
- Our [official website ](https://unit.nginx.org/ ) may provide answers
not easily found otherwise.
- Get involved with the project by contributing! See the
[contributing guide ](CONTRIBUTING.md ) for details.
- To reach the team directly, subscribe to the
[mailing list ](https://mailman.nginx.org/mailman/listinfo/unit ).
2024-03-11 13:37:40 +00:00
- For security issues, [email us ](mailto:security-alert@nginx.org ),
mentioning NGINX Unit in the subject and following the [CVSS
2022-05-13 16:13:23 +00:00
v3.1](https://www.first.org/cvss/v3.1/specification-document) spec.