unit/README.md

NGINX Unit

Universal Web App Server

NGINX Unit is a lightweight and versatile open-source server that has three core capabilities:

• acts as an HTTP reverse proxy,
• serves static media assets,
• runs application code in seven languages.

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.

Its native RESTful JSON API enables dynamic 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.

Quick Installation

macOS

$ brew install nginx/unit/unit

For details and available language packages, see the docs.

Docker

$ docker pull docker.io/nginx/unit

For a description of image tags, see the docs.

Amazon Linux, Fedora, RedHat

$ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit && chmod +x setup-unit
# ./setup-unit repo-config && yum install unit
# ./setup-unit welcome

For details and available language packages, see the docs.

Debian, Ubuntu

$ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit && chmod +x setup-unit
# ./setup-unit repo-config && apt install unit
# ./setup-unit welcome

For details and available language packages, see the docs.

Running a Hello World App

Suppose you saved a PHP script as /www/helloworld/index.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:

{
    "helloworld": {
        "type": "php",
        "root": "/www/helloworld/"
    }
}

Saving it as a file isn't necessary, but can come in handy with larger objects.

Now, PUT it into the /config/applications section of Unit's control API, usually available by default via a Unix domain socket:

# curl -X PUT --data-binary @config.json --unix-socket  \
       /path/to/control.unit.sock http://localhost/config/applications

{
	"success": "Reconfiguration done."
}

Next, reference the app from a listener object in the /config/listeners section of the API. This time, we pass the config snippet straight from the command line:

# curl -X PUT -d '{"127.0.0.1:8000": {"pass": "applications/helloworld"}}'  \
       --unix-socket /path/to/control.unit.sock http://localhost/config/listeners

{
    "success": "Reconfiguration done."
}

Now Unit accepts requests at the specified IP and port, passing them to the application process. Your app works!

$ curl 127.0.0.1:8080

      Hello, PHP on Unit!

Finally, query the entire /config section of the control API:

# curl --unix-socket /path/to/control.unit.sock http://localhost/config/

Unit's output should contain both snippets, neatly organized:

{
    "listeners": {
        "127.0.0.1:8080": {
            "pass": "applications/helloworld"
        }
    },

    "applications": {
        "helloworld": {
            "type": "php",
            "root": "/www/helloworld/"
        }
    }
}

For full details of configuration management, see the docs.

Community

• The go-to place to start asking questions and share your thoughts is our Slack channel.

• Our GitHub issues page offers space for a more technical discussion at your own pace.

• The project map on GitHub sheds some light on our current work and plans for the future.

• Our official website may provide answers not easily found otherwise.

• Get involved with the project by contributing! See the contributing guide for details.

• To reach the team directly, subscribe to the mailing list.

• For security issues, email us, mentioning NGINX Unit in the subject and following the CVSS v3.1 spec.