Igor Sysoev eb1b4b99b1 Shortened titles in README.md and dispensable information.

2017-09-06 18:40:06 +03:00

20 KiB

Raw Blame History

NGINX Unit

About
Installation
Configuration
Contribution
Troubleshooting

About

NGINX Unit is a dynamic web application server, designed to run applications in multiple languages. Unit is lightweight, polyglot, and dynamically configured via API. The design of the server allows reconfiguration of specific application parameters as needed by the engineering or operations.

NGINX Unit is currently available as a beta. As such, it is suitable for use in a testing environment, but is not recommended for use in production.

Installation

System Requirements

NGINX Unit is tested to compile and run on the following systems:

Linux 2.6 or later
FreeBSD 9 or later
MacOS X
Solaris 11

Architectures:

i386
amd64
powerpc
arm

For applications running in NGINX Unit you need the respective programming languages:

Python 2.6, 2.7, 3
PHP 5, 7
Go 1.6 or later

You can run multiple versions of the same language installed on the same system.

Precompiled Packages

Precompiled binaries for Unit are available for CentOS 7.0 and Ubuntu 16.04 LTS.

CentOS Packages

Create the file /etc/yum.repos.d/unit.repo with the following contents:

[unit]
name=unit repo
baseurl=http://nginx.org/packages/centos/7/$basearch/
gpgcheck=0
enabled=1

Download the Unit package:

# apt-get update
# apt-get install unit

Ubuntu Packages

Download the key used to sign the NGINX, Inc. repository and packages.
Add the key to the apt program's keyring. The program can then authenticate the NGINX repository signature, which eliminates warnings about a missing PGP key during installation of the Unit package.

# sudo apt-key add nginx_signing.key

Append the following to the end of the file /etc/apt/sources.list:

deb http://nginx.org/packages/ubuntu/ xenial unit
deb-src http://nginx.org/packages/ubuntu/ xenial unit

Download the Unit package:

# apt-get update
# apt-get install unit

Source code

This section explains how to compile and install Unit from the source code.

Getting Sources

There are three ways to obtain the Unit source code: from the NGINX, Inc. Mercurial repository, from GitHub, or in a tarball.

In each case, the sources are placed in the unit subdirectory of the current working directory.

Mercurial Repository

If don't already have the Mercurial software, download and install it. For example, on Ubuntu systems, run this command:

# apt-get mercurial

Download the Unit sources:

# hg clone hg.nginx.org/unit

GitHub Repository

If don't already have the Git software, download it. See the GitHub documentation.
Download the Unit sources:

# git clone https://github.com/nginx/unit

Tarball

TBD

Installing Required Software

Before configuring and compiling Unit, you must install the required build tools plus the library files for each of the available languages (Go, PHP, and Python) that you want to support.

Ubuntu Prerequisites

Install the build tools.

# apt-get install build-essential

For Go applications support, install the golang package.

# apt-get install golang

For PHP applications support, install the php-dev and libphp-embed packages.

# apt-get install php-dev
# apt-get install libphp-embed

For Python applications support, install the python-dev package.

# apt-get install python-dev

CentOS Prerequisites

Install the build tools.

# yum install gcc make

For Go applications support, install the golang package.

# yum install golang

For PHP applications support, install the php-devel and php-embedded packages.

# yum install php-devel php-embedded

For Python applications support, install the python-devel package.

# yum install python-devel

Configuring Sources

With Unit, you can simultaneously run applications that use different versions of a supported language (Go, PHP, or Python). You need to configure a separate Unit module for each one. The following commands create the necessary instructions in the Makefile for each module.

Configuring Go Package

NGINX Unit will provide the Go package that is required for running your Go application inside Unit.

Set the GOPATH environment variable, which sets the output directory for the Unit Go package.

# export GOPATH=/home/user/go_apps

Run the following command:

# ./configure go
configuring Go package
checking for Go ... found
 + go version go1.6.2 linux/amd64
 + Go package path: "/home/user/go_apps"
 ```

##### Building the Go Applications

1. Modify the source file for the Go application, making changes in two
places:

    a. In the `import` section, add `"unit"` on a separate line.

   ```
   import {
       "fmt"
       "net/http"
       "unit"
   }
   ```

    b. In the `main()` function, comment out the `http.ListenandServe`
    function and insert the `unit.ListenAndServe` function.

   ```
   func main() {
        http.HandleFunc("/", handler)
        //http.ListenAndServe(":8080", nil)
        unit.ListenAndServe(":8080", nil)
   ```

2. Build the Go application.

   ```
   # go build
   ```

If the Go application is executed directly, the unit module will fall back to
the http module. If the Go application is launched by Unit, it will communicate
with the Unit router via shared memory.

##### Configuring PHP Modules

To configure a Unit module (called **php.unit.so**) for the most recent version
of PHP that the `configure` script finds bundled with the operating system, run
this command:

./configure php


To configure Unit modules for other versions of PHP (including versions you
have customized), repeat the following command for each one:

./configure php --module= --config= --lib-path=


where

   * `--module` sets the filename prefix for the Unit module specific to the
   PHP version (that is, the resulting module is called
   &lt;_prefix_&gt;.**unit.so**).

   * `--config` specifies the filename of the **php-config** script for the
   particular version of PHP.

   * `--lib-path` specifies the directory for the PHP library file to use.

For example, this command generates a module called **php70.unit.so** for
PHP&nbsp;7.0:

./configure php --module=php70 \

              --config=/usr/lib64/php7.0/php-config  \
              --lib-path=/usr/lib64/php7.0/lib64

configuring PHP module checking for PHP ... found

PHP version: 7.0.22-0ubuntu0.16.04.1
PHP SAPI: [apache2handler embed cgi cli fpm] checking for PHP embed SAPI ... found
PHP module: php70.unit.so


##### Configuring Python Modules

To configure a Unit module (called **python.unit.so**) for the most recent
version of Python that the `configure` script finds bundled with the operating
system, run this command.

./configure python


To configure Unit modules for other versions of Python (including versions you
have customized), repeat the following command for each one:

./configure python --module= --config=


where

   * `--module` sets the filename prefix for the Unit module specific to the
   Python version (that is, the resulting modules is called
   &lt;_prefix_&gt;.**unit.so**).

   * `--config` specifies the filename of the **python-config** script for the
   particular version of Python.

For example, this command generates a module called **py33.unit.so** for
Python&nbsp;3.3:

./configure php --module=py33 \

              --config=python-config-3.3

configuring Python module checking for Python ... found checking for Python version ... 3.3

Python module: py33.unit.so


#### Compiling Sources

To compile the Unit executable and all configured modules for PHP, Python, or
both, run this command:

make all


To compile the packages for Go:

   1. Verify that the `GOPATH` environment variable is set correctly, or set
   the `GOPATH` variable.

go env GOPATH

export GOPATH=


2. Compile and install the package:

make go-install


#### Installing from Sources

To install Unit with all modules and Go packages, run the following command:

make install


<!-- /section:2 -->

<!-- section:3 -->

## Configuration

By default, the Unit API is available in the control socket file
**unit.control.sock**.

### Applications

For each application, you use the API to define a JSON object in the
`applications` section of the Unit configuration. The JSON object defines
several characteristics of the application, including the language it's written
in, the number of application worker processes to run, the directory with
the file or files for the application, and parameters that vary by language.

This example runs three workers of the PHP application named **blogs** using the
files found in the **/www/blogs/scripts** directory. The default launch file
when the URL doesn't specify the PHP file is **index.php**.

{ ... "applications": { "blogs": { "type": "php", "workers": 20, "root": "/www/blogs/scripts", "index": "index.php" } } }


### Listeners

For an application to be accessible via HTTP, you must define at least
one listener for it in the `listeners` section of the Unit configuration. A
listener is an IP address and port on which Unit listens for client requests to
a named application. The IP address can be either a full address (for example,
`127.0.0.1:8300`) or a wildcard (for example, ``*:8300`).

In this example, requests received on port&nbsp;8300 are sent to the **blogs**
application:

 ```
 {
      "listeners": {
          "*:8300": {
              "application": "blogs"
          }
      },
      ...
 }
 ```


For complete details about the JSON objects for each language, see
[JSON Specification for Listener and Application Objects](#json-specification-for-listener-and-application-objects).

### Minimum Configuration

The configuration must include at least one listener and associated
application, as in this example:

{ "listeners": { "*:8300": { "application": "blogs" } }, "applications": { "blogs": { "type": "php", "workers": 20, "root": "/www/blogs/scripts", "index": "index.php" } } }


### Creating Configuration Objects

To create a configuration object, specify the JSON data for it in the body of
a `PUT` request. To reduce errors, it makes sense to write the JSON data in a
file and specify the file path with the `-d` option to the `curl` command.

#### Example: Create a Full Configuration

Create an initial configuration by uploading the contents of the **start.json**
file:

curl -X PUT -d @/path/to/start.json \

   --unix-socket ./control.unit.sock http://localhost/


#### Example: Create an Application Configuration

Create a new application object called **wiki** from the file **wiki.json**.

curl -X PUT -d @/path/to/wiki.json \

   --unix-socket ./control.unit.sock http://localhost/applications/wiki


The contents of **wiki.json** are:

{ "type": "python", "workers": 10, "module": "wsgi", "user": "www-wiki", "group": "www-wiki", "path": "/www/wiki" }


### Displaying Configuration Objects

To display a configuration object, append its path to the `curl` URL.

#### Example: Display the Full Configuration

Display the complete configuration:

curl --unix-socket ./control.unit.sock http://localhost/

{ "applications": { "blogs": { "type": "php", "user": "nobody", "group": "nobody", "workers": 20, "root": "/www/blogs/scripts", "index": "index.php" },

   "wiki": {
      "type": "python",
      "user": "nobody",
      "group": "nobody",
      "workers": 10,
      "path": "/www/wiki",
      "module": "wsgi"
   }
},

"listeners": { "*:8300": { "application": "blogs" },

  "*:8400": {
     "application": "wiki"
  }

} }


#### Example: Display One Object

Display the data for the **wiki** application:

curl --unix-socket ./control.unit.sock http://localhost/applications/wiki

{ "type": "python", "workers": 10, "module": "wsgi", "user": "www", "group": "www", "path": "/www/wiki" }


### Modifying Configuration Objects

To change a configuration object, use the `-d` option to the `curl` command to
specify the object's JSON data in the body of a `PUT` request.

#### Example: Change the Application for a Listener

Change the `application` object to **wiki-dev** for the listener on *:8400:

curl -X PUT -d '"wiki-dev"' --unix-socket ./control.unit.sock \

   'http://localhost/listeners/*:8400/application'

{ "success": "Reconfiguration done." }


#### Example: Change the File Path for an Application

Change the `root` object for the **blogs** application to
**/www/blogs-dev/scripts**:

curl -X PUT -d '"/www/blogs-dev/scripts"' \

   --unix-socket ./control.unit.sock  \
   http://localhost/applications/blogs/root

{ "success": "Reconfiguration done." }


### Deleting Configuration Objects

To delete a configuration object, make a `DELETE` request and append the
object's path to the `curl` URL.

#### Example: Delete a Listener

Delete the listener on *:8400:

curl -X DELETE --unix-socket ./control.unit.sock \

   'http://localhost/listeners/*:8400'

{ "success": "Reconfiguration done." }


### Listener and Application Objects

#### Listener

|  Object | Description |
| --- | --- |
| `<IP-address>:<port>`          | IP address and port on which Unit listens for requests to the named application. The IP address can be either a full address (`127.0.0.1:8300`) or a wildcard (`*:8300`).
| `application`                  | Application name.

Example:

"*:8300": { "application": "blogs" }


#### Go Application

|  Object | Description |
| --- | --- |
| `type`| Type of the application (`go`).
| `workers`           | Number of application workers.
| `executable`        | Full path to compiled Go app.
| `user` (optional)   | Username that runs the app process. <br/><br/>If not specified, `nobody` is used.
| `group` (optional)  | Group name that runs the app process. <br/><br/> If not specified, user's primary group is used.

Example:

"go_chat_app": { "type": "go", "executable": "/www/chat/bin/chat_app", "user": "www-go", "group": "www-go" }


#### PHP Application

|  Object | Description |
| --- | --- |
| `type`| Type of the application (`php`).
| `workers`           | Number of application workers.
| `root`              | Directory to search for PHP files.
| `index`             | Default launch file when the PHP file name is not specified in the URL.
| `script` (optional) | File that Unit runs for every URL, instead of searching for a file in the filesystem. The location is relative to the root.
| `user` (optional)   | Username that runs the app process. <br/><br/>If not specified, `nobody` is used.
| `group` (optional)  | Group name that runs the app process. <br/><br/> If not specified, user's primary group is used.

Example:

"blogs": { "type": "php", "workers": 20, "root": "/www/blogs/scripts", "index": "index.php", "user": "www-blogs", "group": "www-blogs" },


#### Python Application

|  Object | Description |
| --- | --- |
| `type`| Type of the application (`python`).
| `workers`           | Number of application workers.
| `path`             | Path to search for the **wsgi.py** file.
| `module`             | Required. Currently the only supported value is `wsgi`.
| `user` (optional)   | Username that runs the app process. <br/><br/>If not specified, `nobody` is used.
| `group` (optional)  | Group name that runs the app process. <br/><br/> If not specified, user's primary group is used.

Example:

"shopping_cart": { "type": "python", "workers": 10, "path": "/www/store/cart", "module": "wsgi", "user": "www", "group": "www" },


#### Full Example

{ "listeners": { ":8300": { "application": "blogs" }, ":8400": { "application": "wiki" }, ":8401": { "application": "shopping_cart" }, ":8500": { "application": "go_chat_app" } }, "applications": { "blogs": { "type": "php", "workers": 20, "root": "/www/blogs/scripts", "user": "www-blogs", "group": "www-blogs", "index": "index.php" }, "wiki": { "type": "python", "workers": 10, "user": "www-wiki", "group": "www-wiki", "path": "/www/wiki" }, "shopping_cart": { "type": "python", "workers": 10, "module": "wsgi", "user": "www", "group": "www", "path": "/www/store/cart" }, "go_chat_app": { "type": "go", "user": "www-chat", "group": "www-chat", "executable": "/www/chat/bin/chat_app" } } }


<!-- /section:3 -->

<!-- section:4 -->

## Contribution

NGINX Unit is released under the Apache 2.0 license.

To contribute changes, either submit them by email to <unit@nginx.org> or
submit a pull request in the https://github.com/nginx/unit repository.

<!-- /section:4 -->

<!-- section:5 -->

## Troubleshooting

**TBD**

<!-- /section:5 -->

20 KiB Raw Blame History

NGINX Unit

About

Installation

System Requirements

Precompiled Packages

CentOS Packages

Ubuntu Packages

Source code

Getting Sources

Mercurial Repository

GitHub Repository

Tarball

Installing Required Software

Ubuntu Prerequisites

CentOS Prerequisites

Configuring Sources

Configuring Go Package

./configure php

./configure php --module= --config= --lib-path=

./configure php --module=php70 \

./configure python

./configure python --module= --config=

./configure php --module=py33 \

make all

go env GOPATH

export GOPATH=

make go-install

make install

curl -X PUT -d @/path/to/start.json \

curl -X PUT -d @/path/to/wiki.json \

curl --unix-socket ./control.unit.sock http://localhost/

curl --unix-socket ./control.unit.sock http://localhost/applications/wiki

curl -X PUT -d '"wiki-dev"' --unix-socket ./control.unit.sock \

curl -X PUT -d '"/www/blogs-dev/scripts"' \

curl -X DELETE --unix-socket ./control.unit.sock \

20 KiB

Raw Blame History