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
Perl 5.12 or later
Ruby 2.0 or later

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

Docker Images¶

To install and run Unit from our Docker image repository:

# docker pull nginx/unit
# docker run -d nginx/unit

By default, the :latest image tag is used that resolves into a -full configuration of the latest Unit version. Other tags available:

Tag	Description
`<version>-full`	Modules for all supported languages.
`<version>-minimal`	No language modules.
`<version>-<language>`	Specific language module only, for example `1.3-ruby2.3` or `1.2-python2.7`.

For further details, see the repository page.

Precompiled Packages¶

Precompiled binaries for Unit are available for:

CentOS 6, 7

RHEL 6, 7

Amazon Linux

Ubuntu 16.04, 17.10, 18.04

Debian 8, 9

CentOS Packages¶

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

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

Install Unit base package:
```
# yum install unit
```
Install additional module packages you would like to use, e.g.:
```
# yum install unit-php unit-python unit-go unit-perl
```

RHEL Packages¶

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

[unit]
name=unit repo
baseurl=https://packages.nginx.org/unit/rhel/$releasever/$basearch/
gpgcheck=0
enabled=1

Install Unit base package:
```
# yum install unit
```

Install additional module packages you would like to use.

For RHEL 6:

# yum install unit-php unit-python unit-perl

For RHEL 7:

# yum install unit-php unit-python unit-go unit-perl

Amazon Linux Packages¶

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

[unit]
name=unit repo
baseurl=https://packages.nginx.org/unit/amzn/$releasever/$basearch/
gpgcheck=0
enabled=1

For Amazon Linux 2 LTS:

[unit]
name=unit repo
baseurl=https://packages.nginx.org/unit/amzn2/$releasever/$basearch/
gpgcheck=0
enabled=1

Install Unit base package:
```
# yum install unit
```

Install additional module packages you would like to use, e.g.:

# yum install unit-php unit-python27 unit-python34 unit-python35 unit-python36 unit-go unit-perl

For Amazon Linux 2 LTS:

# yum install unit-php unit-python unit-go unit-perl

Ubuntu Packages¶

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

Create the /etc/apt/sources.list.d/unit.list file with the following contents.

For Ubuntu 16.04:

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

For Ubuntu 17.10:

deb https://packages.nginx.org/unit/ubuntu/ artful unit
deb-src https://packages.nginx.org/unit/ubuntu/ artful unit

For Ubuntu 18.04:

deb https://packages.nginx.org/unit/ubuntu/ bionic unit
deb-src https://packages.nginx.org/unit/ubuntu/ bionic unit

Install Unit base package:

# apt-get update
# apt-get install unit

Install additional module packages you would like to use.

For Ubuntu 16.04:

# apt-get install unit-php unit-python2.7 unit-python3.5 unit-go unit-perl unit-ruby

For Ubuntu 17.10:

# apt-get install unit-php unit-python2.7 unit-python3.6 unit-go1.8 unit-go1.9 unit-perl unit-ruby

For Ubuntu 18.04:

# apt-get install unit-php unit-python2.7 unit-python3.6 unit-go1.9 unit-go1.10 unit-perl unit-ruby

Debian Packages¶

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

Create the /etc/apt/sources.list.d/unit.list file with the following contents.

For Debian 8:

deb https://packages.nginx.org/unit/debian/ jessie unit
deb-src https://packages.nginx.org/unit/debian/ jessie unit

For Debian 9:

deb https://packages.nginx.org/unit/debian/ stretch unit
deb-src https://packages.nginx.org/unit/debian/ stretch unit

Install Unit base package:

# apt-get update
# apt-get install unit

Install additional module packages you would like to use.

For Debian 8:

# apt-get install unit-php unit-python2.7 unit-python3.4 unit-perl unit-ruby

For Debian 9:

# apt-get install unit-php unit-python2.7 unit-python3.5 unit-go1.7 unit-go1.8 unit-perl unit-ruby

Community Repositories¶

Warning: Distributions listed in this section are maintained by their respective communities. NGINX has no control or responsibility over these resources. Proceed at your own consideration.

FreeBSD¶

To install Unit using FreeBSD packages, update the repository and install the package:

# pkg install -y unit

To install Unit using FreeBSD ports, update your port collection.

For portsnap:

# portsnap fetch update

For svn:

# svn update /usr/ports

Next, browse to the port path to build and install the port:

# cd /usr/ports/www/unit
# make
# make install

Warning: make here is used in port configuration. For make commands to build Unit from the code in our repositories, see Source Code.

Gentoo¶

To install Unit using Portage, update the repository and install the package:

# emerge --sync
# emerge www-servers/nginx-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 you don’t already have the Mercurial software, download and install it. For example, on Ubuntu systems, run this command:
```
# apt-get install mercurial
```
Download the Unit sources:
```
# hg clone https://hg.nginx.org/unit
```

GitHub Repository¶

If you 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¶

Unit source code tarballs are available at https://unit.nginx.org/download/.

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
```
For Perl applications support, install the libperl-dev package:
```
# apt-get install libperl-dev
```
For Ruby applications support, install the ruby-dev package:
```
# apt-get install ruby-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
```
For Perl applications support, install the perl-devel and perl-libs packages:
```
# yum install perl-devel perl-libs
```
For Ruby applications support, install the ruby-devel package:
```
# yum install ruby-devel
```

Configuring Sources¶

First you need to run configure script to perform necessary system checks and generate Makefile required to compile all other stuff:

# ./configure

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"

Install the Go package in your working GOPATH:
```
# make go-install
```

Building the Go Applications¶

Modify the source file for the Go application, making changes in two places:
1. In the import section, add "nginx/unit" on a separate line:
```
import (
    "fmt"
    "net/http"
    "nginx/unit"
)
```
2. 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)
}
```
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 Perl Modules¶

To configure a Unit module (called perl.unit.so) for the version of Perl that the configure script finds bundled with the operating system, run this command:

# ./configure perl

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

# ./configure perl OPTIONS

where OPTIONS can be:

`--module=<prefix>`
	Sets the filename prefix for the Unit module specific to the Perl version (that is, the resulting module is called <prefix>.unit.so).
`--perl=<perl>`	Specifies the particular Perl interpreter.
`--include=<directory>`
	Specifies the directory for the Perl headers files to use.

For example, this command generates a module called perl-5.20.unit.so for Perl 5.20.2:

$ ./configure perl --module=perl-5.20 \
                   --perl=perl5.20.2
configuring Perl module
checking for Perl ... found
 + Perl version: 5.20.2
 + Perl module: perl-5.20.unit.so

Configuring PHP Modules¶

To configure a Unit module (called php.unit.so) for the 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 OPTIONS

where OPTIONS can be:

`--module=<prefix>`
	Sets the filename prefix for the Unit module specific to the PHP version (that is, the resulting module is called <prefix>.unit.so).
`--config=<script>`
	Specifies the php-config script for the particular version of PHP.
`--lib-path=<directory>`
	Specifies the directory for the PHP library file to use.
`--lib-static`	Enables linking with static library.

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

# ./configure php --module=php70  \
                  --config=/usr/lib64/php7.0/bin/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 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 OPTIONS

where OPTIONS can be:

`--module=<prefix>`
	Sets the filename prefix for the Unit module specific to the Python version (that is, the resulting module is called <prefix>.unit.so).
`--config=<script>`
	Specifies the python-config script for the particular version of Python.
`--lib-path=<directory>`
	Specifies the directory for the Python library file to use.

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

# ./configure python --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

Configuring Ruby Modules¶

To configure a Unit module (called ruby.unit.so) for the version of Ruby that the configure script finds bundled with the operating system, run this command:

# ./configure ruby

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

# ./configure ruby OPTIONS

where OPTIONS can be:

`--module=<prefix>`
	Sets the filename prefix for the Unit module specific to the Ruby version (that is, the resulting module is called <prefix>.unit.so).
`--ruby=<ruby>`	Specifies the particular Ruby interpreter.

For example, this command generates a module called ru23.unit.so for Ruby 2.3:

# ./configure ruby --module=ru23  \
                   --ruby=ruby23
configuring Ruby module
checking for Ruby ... found
 + Ruby version: 2.3.0
 + Ruby module: ru23.unit.so

Configuring SSL/TLS Support¶

To enable SSL/TLS support in Unit, use the --openssl option with ./configure:

# ./configure --openssl

Note

Make sure that OpenSSL (1.0.1 and later) header files and libraries are available in your compiler’s search path.

To customize the path, provide the --cc-opt and --ld-opt options for ./configure.
Also, you can set custom CFLAGS and LDFLAGS environment variables before running ./configure.

For more information about further SSL/TLS configuration, see SSL/TLS and Certificates.

Compiling Sources¶

To compile the Unit executable and all configured modules run this command:

# make all

Installing from Sources¶

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

# make install