NGINX Unit Cookbook

Chapter 4. Usage and Operations

Introduction

Understanding how to start and stop the NGINX Unit server, and the applications it runs, is essential. In this chapter you will learn how to start and stop the Unit service on init.d and systemd service managers, as well as how to start the Unit server in the foreground. This chapter also details how to submit the configuration objects to the Unit control API in order to start serving the application.

Startup and Shutdown

Problem

You need to start or stop the NGINX Unit server.

Solution

When Unit is installed through a repository, a startup file for a service manager such as, init.d or systemd is also installed and configured. These service managers will start Unit as a daemon.

Start Unit on an init.d system:

sudo /etc/init.d/unit start

Stop Unit on an init.d system:

sudo /etc/init.d/unit stop

Start Unit on a systemd system:

sudo systemclt start unit

Stop Unit on a systemd system:

sudo systemclt stop unit

Start Unit in the foreground. The following assumes that the Unit binary is installed into a directory defined in your PATH:

sudo unitd --no-daemon

Discussion

The service manager used to start the Unit daemon depends on the type of system it’s running on. Each service manager has its own syntax for starting and stopping services. The service managers will start Unit as a daemon. An example of starting Unit in the foreground is also shown. This can be useful for testing, or when running Unit in a Docker container.

Applying Configuration

Problem

You need to start an application within NGINX Unit.

Solution

For this section, it’s important to understand that the Unit configuration is represented as a single JSON object. Portions of the object can be interacted with in a RESTful manner. The following will be examples of working with specific application and listener objects, and then with the Unit config as a whole. 

Locate the Unit control socket; example output is provided. The default value found in this example, /var/run/control.unit.sock, will be used throughout the book. As the control socket is owned by root by default, all curl commands will be run with sudo.

unitd -h

unit options:

  --version            print unit version and configure options

  --no-daemon          run unit in non-daemon mode

  --control ADDRESS    set address of control API socket
                       default: "unix:/var/run/control.unit.sock"
  ...
  ...

Create an application by submitting an application object to the control socket:

sudo curl -X PUT -d @/path/to/application-object.json \
       --unix-socket /var/run/control.unit.socket \
       http://localhost/config/applications/app-name

Configure a listener and direct it to the application:

Warning

This command removes all other listeners that might have been defined prior.

sudo curl -X PUT \
       -d '{"*:8080":{"pass":"applications/app-name"}}' \
       --unix-socket /var/run/control.unit.socket \
       http://localhost/config/listeners

You alternatively can create both objects at once by defining both the application and the listener object in one configuration file. Create a file named php-app.json:

{
    "listeners": {
        "*:8080": {
            "pass": "applications/app-name"
        }
    },
    "applications": {
        "app-name": {
            "type": "php",
            "processes": 20,
            "root": "/var/www/app/",
            "index": "index.php"
        }
    }
}

Submit the php-app.json configuration to the NGINX Unit control socket:

Warning

This command removes all other listeners, apps, and routes, that might have been defined prior.

sudo curl -X PUT -d @php-app.json  \
       --unix-socket /var/run/control.unit.sock \
       http://localhost/config/

Test your application:

curl localhost:8080

Discussion

All interactions with Unit are done through the control interface. The API is RESTful; applications and configurations are created, altered, or deleted through the API. In the examples for this solution, we build on the examples from Chapter 3 by submitting them to the Unit control interface. The alternate approach is to define all applications, routes, and listener objects in one JSON file and submit them together to the Unit configuration.