Unit 0.3 Beta Release Available Now

On Dec 28th, we released the third beta version of NGINX Unit, the new dynamic web and application server. In this blog post, we will review and discuss the latest changes in detail.

If you have Unit 0.2 installed from our package repositories, upgrade using your package manager. If you are performing a fresh installation, see the installation documentation for details: https://unit.nginx.org/installation/. (We now provide pre-built packages for more operating systems.)

HTTP Keep-Alive

HTTP persistent connections, or HTTP keep-alive, is the technology used to keep TCP connections open between requests. This reduces latency and improves the performance of the web site. NGINX Unit now uses keep-alive connections by default. You don’t have to configure anything on the Unit side to have this enabled.

Keep-alive functionality is managed by the HTTP headers Connection and Keep-Alive. Unit sets the keep-alive timeout to 65 seconds. In a future release, we will add the ability for users to change the keep-alive timeout.

When Unit is installed behind NGINX, you need to configure it correctly to utilize HTTP keep-alive:

Add the keepalive directive for the upstream
Set the correct value for proxy_http_version in order to use HTTP/1.1 for proxying
Remove any existing client’s Connection headers

See the following short example of NGINX configuration with these directives in use.

http {

    upstream unit {

        server 127.0.0.1:8080;

           keepalive 32;

    }

    server {

        location / {

            proxy_pass http://unit;

            proxy_set_header Connection '';

            proxy_http_version 1.1;

        }

    }

}

Python Virtual Environments

Python allows you to create isolated virtual environments for your applications. This feature is useful for creating multiple apps that use different versions of Python, different packages, and/or different libraries, and that need to run simultaneously in the same system. Running a virtual environment will also, in many cases, remove the need for developers to have root access to the system. Now, with Unit version 0.3, you can use virtual environments across multiple Python applications.

You can create a virtual environment using the virtualenv tool. Once you create a virtual environment, you can define it with the Unit API, using the home parameter of your application. If you did not configure PYTHONPATH inside your virtual environment, you still need to set up the path and home parameters in the configuration of your application through the Unit API. They might refer to the same, or to different directories.

An example Unit configuration is shown below:

{

    "listeners": {

        "*:8080": {

            "application": "example-myblog"

        }

    },
    "applications": {

        "example-myblog": {

                "type": "python 3",

                "workers": 2,

                "module": "wsgi",

                "user": "nick",

                "group": "nick",

                "path": "/home/nick/myblog-virtualenv/scripts",

                "home": "/home/nick/myblog-virtualenv"

            }

    }

}

This example displays how to configure the following system:

Unit listens on port 8080 for all IP addresses of the system
Application example-myblog is created by the Unit administrator
A virtual environment is created by user nick in the directory /home/nick/myblog-virtualenv
Python scripts are located in /home/nick/myblog-virtualenv/scripts

Alternatively, you can set up both path and home relative to the value of working_directory:

...

"working_directory": "/home/nick/myblog-virtualenv",

"path": "scripts",

"home": ".",

...

In order to change the existing application object to use virtual environments, use the Unit API to change one parameter directly. You don’t have to reload or restart the server. The current state of Unit will be preserved automatically. Here’s the example:

$ curl -X PUT -d '"/home/nick/myblog-virtualenv"' --unix-socket /path/to/control.unit.sock http://localhost/applications/example-myblog/home

To display the current value of the home parameter, use the GET request to the API:

$ curl -X GET --unix-socket /path/to/control.unit.sock http://localhost/applications/example-myblog/home

Python atexit

The atexit module in Python defines a single function to register cleanup functions. The functions run when an application process performs a normal shutdown. Unit now supports atexit behavior. You don’t have to change anything in the application or in Unit configuration in order to use atexit. See https://github.com/nginx/unit/issues/65 and https://github.com/nginx/unit/commit/be36cf52c8b092ebb688784a1c10626cac2138d7 for implementation details.

Go Package Changes

The Go package name for Unit has changed from unit to nginx/unit. This name is more consistent with other packages in the Go ecosystem. Prior to compiling your Go app for Unit, make sure you have the package compiled and installed. For supported systems, you can install the unit-go package from our repositories. Then, in the source of the Go app, import the nginx/unit package, together with the net/http package:

import (

    "fmt"

    "net/http"

    "nginx/unit"

)

Application Timeouts

Unit can now respond with an HTTP error to the client when workers exceed their execution timeout. With version 0.3, the application start time and time in the queue are no longer included in the timeout calculation.

In order to enable timeouts for workers, change the limits.timeout property of the application, using the API.

$ curl -X PUT -d '{"timeout": 10}' --unix-socket http://localhost:8088/applications/example-myblog/limits

The timeout value is defined in seconds.

A full application object example with the timeout value defined will look like the following.

{

    "type": "python 3",

    "workers": 2,

    "module": "wsgi",

    "user": "nick",

    "group": "nick",

    "path": "/home/nick/myblog-virtualenv/scripts",

    "home": "/home/nick/myblog-virtualenv",

    "limits": {

        "timeout": 10

    }

}

Timeouts can be enabled for all supported application languages: PHP, Python, and Go.

In larger deployments, various URLs, scripts, or workflows might need different timeout restrictions. In that case, have these different paths defined as different locations in the NGINX reverse proxy, then create several different applications in Unit. You can have different applications use the same directories and application files, or various directories and application files.

Number of Requests per Worker

Unit can now limit the number of requests executed in one worker process of the application. When the number is exceeded, it will restart the worker. This feature is particularly useful when the applications tend to leak memory, or otherwise misbehave after too many requests.

To enable this, change the limits.requests property of the application using the API.

$ curl -X PUT -d '{"requests": 1000}' --unix-socket http://localhost:8088/applications/example-myblog/limits

A full application object example, with the number of requests per worker enabled, will look like the following.

{

    "type": "python 3",

    "workers": 2,

    "module": "wsgi",

    "user": "nick",

    "group": "nick",

    "path": "/home/nick/myblog-virtualenv/scripts",

    "home": "/home/nick/myblog-virtualenv",

    "limits": {

        "timeout": 10,

        "requests": 1000

    }

}

This limit can be enabled for all supported application languages: PHP, Python, and Go.

Miscellaneous

In addition to the features described above, we added a number of smaller bug fixes and minor changes. These include:

Precompiled packages are available for more operating systems in our repositories:

CentOS 6
CentOS 7
Debian 8 (Jessie)
Debian 9 (Stretch)
Ubuntu 16.04
Ubuntu 17.04
Ubuntu 17.10

Various Go package improvements that simplify the code and increase performance through better integration between the C code of Unit and Go code.
The Unit version is now verified in the Go package to avoid incompatible package usage.
Improved application worker selection, request canceling, and request rescheduling. A new algorithm minimizes request processing latency.
Addition of a new testing framework. With this release, Unit has a number of functionality tests that we run regularly. See them in the test directory in the repositories. We will be regularly adding more tests to improve test coverage in future.