Installation§

You can install NGINX Unit in four alternative ways:

Choose from our official binary packages for a few popular systems. They are as easy to use as any other packaged software and suit most purposes straight out of the box.
If your preferred OS or language version is missing from the official package list, try third-party repositories. Be warned, though: we don’t maintain them.
Run our official Docker images, prepackaged with varied language combinations.
To fine-tune Unit to your goals, download the sources, install the toolchain, and build a custom binary from scratch; just make sure you know what you’re doing.

Prerequisites§

Unit compiles and runs on various Unix-like operating systems, including:

FreeBSD 10 or later
Linux 2.6 or later
macOS 10.6 or later
Solaris 11

It also supports most modern instruction set architectures, such as:

ARM
IA-32
PowerPC
MIPS
S390X
x86-64

App languages and platforms that Unit can run (including several versions of the same language):

Go 1.6 or later
Java 8 or later
Node.js 8.11 or later
PHP 5, 7, 8
Perl 5.12 or later
Python 2.6, 2.7, 3
Ruby 2.0 or later

Community Repositories§

Warning

These distributions are maintained by respective communities, not NGINX. Proceed with caution.

Alpine

To install core Unit executables from the Alpine Linux packages:

# apk update
# apk upgrade
# apk add unit

To install service manager files and specific language modules:

# apk add unit-openrc unit-perl unit-php7 unit-python3 unit-ruby

Runtime details:

Control socket	`/run/control.unit.sock`
Log file	`/var/log/unit.log`
Non-privileged user	`unit`
Startup and shutdown	# service unit start # service unit stop

Arch

To install core Unit executables and all language modules, clone the Arch User Repository (AUR):

$ git clone https://aur.archlinux.org/nginx-unit.git
$ cd nginx-unit

Before proceeding further, verify that the PKGBUILD and the accompanying files aren’t malicious or untrustworthy. AUR packages are user produced without pre-moderation; use them at your own risk.

Next, build the package:

$ makepkg -si

Runtime details:

Control socket	`/run/nginx-unit.control.sock`
Log file	`/var/log/nginx-unit.log`
Non-privileged user	`nobody`
Startup and shutdown	# systemctl start unit # systemctl stop unit

CentOS/RHEL SCLs

If you use SCLo Software Collections in your environment, you can install Unit’s PHP modules as packages from the corresponding repo. Besides other dependencies, the packages require the core Unit installation.

CentOS:

# yum install centos-release-scl
# yum install --enablerepo=centos-sclo-sclo \
              sclo-php72-unit-php sclo-php73-unit-php

RHEL:

# cd /etc/yum.repos.d/
# curl -O https://copr.fedorainfracloud.org/coprs/rhscl/centos-release-scl/repo/epel-7/rhscl-centos-release-scl-epel-7.repo
# yum install centos-release-scl
# yum install --enablerepo=centos-sclo-sclo \
              sclo-php72-unit-php sclo-php73-unit-php

FreeBSD

To install Unit from FreeBSD packages, install the core package and other packages you need:

# pkg install -y unit
# pkg install -y libunit
# pkg install -y unit-java8  \
                 unit-perl5.32  \
                 unit-php72 unit-php73 unit-php74 unit-php80  \
                 unit-python27 unit-python37  \
                 unit-ruby2.6

To install Unit from FreeBSD ports, start by updating your port collection.

With portsnap:

# portsnap fetch update

With svn:

# svn update /usr/ports

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

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

Repeat the steps for the other ports you need: libunit (required to install the Node.js module and build Go apps), unit-java, unit-perl, unit-php, unit-python, or unit-ruby.

Runtime details:

Control socket	`/var/run/unit/control.unit.sock`
Log file	`/var/log/unit/unit.log`
Non-privileged user	`www`
Startup and shutdown	# service unitd start # service unitd stop

Gentoo

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

# emerge --sync
# emerge www-servers/nginx-unit

To install specific language modules and features, apply the corresponding USE flags.

Runtime details:

Control socket	`/run/nginx-unit.sock`
Log file	`/var/log/nginx-unit`
Non-privileged user	`nobody`
Startup and shutdown	# openrc -s nginx-unit start # openrc -s nginx-unit stop

Nix

To install core Unit executables and all language modules using the Nix package manager, update the channel, check if Unit’s available, and install the package:

$ nix-channel --update
$ nix-env -qa 'unit'
$ nix-env -i unit

This installs most embedded language modules and such features as SSL or IPv6 support. For a full list of optionals, see the package definition.

Runtime details:

Control socket	`/run/unit/control.unit.sock`
Log file	`/var/log/unit/unit.log`
Non-privileged user	`unit`
Startup and shutdown	Manual

Remi's RPM Repo

Remi’s RPM repository, which hosts the latest versions of the PHP stack for CentOS, Fedora, and RHEL, also has the core Unit package and the PHP modules.

To use Remi’s versions of Unit packages, configure Remi’s RPM repo first. Remi’s PHP language modules are also compatible with the core Unit package from our own repository.

Next, install Unit and the PHP modules you want:

# yum install --enablerepo=remi unit  \
      php54-unit-php php55-unit-php php56-unit-php  \
      php70-unit-php php71-unit-php php72-unit-php php73-unit-php php74-unit-php  \
      php80-unit-php

Runtime details:

Control socket	`/run/unit/control.sock`
Log file	`/var/log/unit/unit.log`
Non-privileged user	`nobody`
Startup and shutdown	# systemctl start unit # systemctl stop unit

Docker Images§

To install and run Unit from NGINX’s Docker image repository:

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

Default image tag is :latest; it resolves into a -full configuration of the latest Unit version. Other tags:

Tag	Description
`1.21.0-full`	Modules for all supported languages.
`1.21.0-minimal`	No language modules.
`1.21.0-<language>`	A specific language module, for example `1.21.0-ruby2.3` or `1.21.0-python2.7`.

We also publish these images as tarballs on our website:

$ curl -O https://packages.nginx.org/unit/docker/1.21.0/nginx-unit-1.21.0-full.tar.gz
$ curl -O https://packages.nginx.org/unit/docker/1.21.0/nginx-unit-1.21.0-full.tar.gz.sha512
$ sha512sum -c nginx-unit-1.21.0-full.tar.gz.sha512
      nginx-unit-1.21.0-full.tar.gz: OK
$ docker load < nginx-unit-1.21.0-full.tar.gz

Note

The control socket’s pathname is /var/run/control.unit.sock. The log is /var/log/unit.log.

For further details, see the repository page and the official Howto.

Initial Configuration§

Official images support initial container configuration, implemented with an ENTRYPOINT script.

First, the script checks the Unit state directory (/var/lib/unit/ in official images) of the container. If it’s empty, the script processes certain file types in the container’s /docker-entrypoint.d/ directory:

File Type	Purpose/Action
`.pem`	Certificate bundles are uploaded under respective names: `cert.pem` to `certificates/cert`.
`.json`	Configuration snippets are uploaded as to the `config` section of Unit’s configuration.
`.sh`	Shell scripts that run in the container after the `.pem` and `.json` files are uploaded.

Note

The script issues warnings about any other file types in the /docker-entrypoint.d/ directory. Also, your shell scripts must have execute permissions set.

This mechanism allows you to customize your containers at startup, reuse configurations, and automate your workflows, reducing manual effort. To use the feature, add COPY directives for certificate bundles, configuration fragments, and shell scripts to your Dockerfile derived from an official image:

FROM nginx/unit:1.21.0-minimal
COPY ./*.pem  /docker-entrypoint.d/
COPY ./*.json /docker-entrypoint.d/
COPY ./*.sh   /docker-entrypoint.d/

Note

Mind that running Unit even once populates its state directory; this prevents the script from executing, so this script-based initialization must occur before you run Unit within your derived image.

This feature comes in handy if you want to tie Unit to a certain app configuration for later use. For ad-hoc initialization, you can mount a directory with configuration files to a container at startup:

$ docker run -d --mount \
         type=bind,src=/path/to/config/files/,dst=/docker-entrypoint.d/ \
         nginx/unit:latest)

Improve this page

`--help`	Displays a summary of common ./configure options. For language-specific details, run ./configure <language> --help or see below.
`--cc=pathname`	Custom C compiler pathname. The default is `cc`.
`--cc-opt=options`, `--ld-opt=options`	Extra options for the C compiler and linker.
`--group=name`, `--user=name`	Group name and username to run Unit’s non-privileged processes. The defaults are `--user`’s primary group and `nobody`, respectively.
`--debug`	Turns on the debug log.
`--no-ipv6`	Turns off IPv6 support.
`--no-unix-sockets`	Turns off Unix domain sockets support.
`--openssl`	Turns on OpenSSL support. 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; you can also set the `CFLAGS` and `LDFLAGS` environment variables before running ./configure. For details, see SSL/TLS and Certificates.

`--no-regex`	Turns off regex support. Attempts to configure a regex will fail validation.
`--no-pcre2`	Instead of PCRE2, the older PCRE 8.x library will be used.

`--prefix=prefix`	Destination directory prefix for path options: `--bindir`, `--sbindir`, `--libdir`, `--incdir`, `--modules`, `--state`, `--pid`, `--log`, and `--control`.
`--bindir=directory`, `--sbindir=directory`	Directory paths for end-user and sysadmin executables. The defaults are `bin` and `sbin`, respectively.
`--control=socket`	Control API socket address in IPv4, IPv6, or Unix domain format: $ ./configure --control=unix:/path/to/control.unit.sock $ ./configure --control=127.0.0.1:8080 $ ./configure --control=[::1]:8080 Warning Avoid exposing an unprotected control socket to public networks. Use NGINX or a different solution such as SSH for security and authentication. The default is `unix:control.unit.sock`, created as `root` with `600` permissions.
`--incdir=directory`, `--libdir=directory`	Directory paths for libunit header files and libraries. The defaults are `include` and `lib`, respectively.
`--log=pathname`	Pathname for Unit’s log. The default is `unit.log`.
`--modules=directory`	Directory path for Unit’s language modules. The default is `modules`.
`--pid=pathname`	Pathname for the PID file of Unit’s daemon process. The default is `unit.pid`.
`--state=directory`	Directory path where Unit’s state (configuration, certificates, other records) is stored between runs. If you migrate your installation, copy the entire directory. Warning Unit’s state includes sensitive data and must be owned by `root` with `700` permissions. Avoid updating the directory by outside means; instead, use Unit’s config API to ensure data consistency. The default is `state`.
`--tmp=directory`	Defines the temporary files location (used to dump large request bodies). The default value is `tmp`.

`--home=directory`	Directory path for Java utilities and header files (required to build the module). The default is the `java.home` setting.
`--jars=directory`	Directory path for Unit’s custom `.jar` files. The default is the Java module path.
`--lib-path=directory`	Directory path for the `libjvm.so` library. The default is based on JDK settings.
`--local-repo=directory`	Directory path for local `.jar` repository. The default is `$HOME/.m2/repository/`.
`--repo=directory`	URL path for remote Maven repository. The default is `http://central.maven.org/maven2/`.
`--module=filename`	Name of the module to be built (`<module>.unit.so`), also used in make targets. The default is `java`.

`--local=directory`	Local directory path for Node.js module installation. By default, the module is installed globally (recommended).
`--node=pathname`	Specific Node.js executable pathname, also used in make targets. The default is `node`.
`--npm=pathname`	Specific NPM executable pathname. The default is `npm`.
`--node-gyp=pathname`	Specific node-gyp executable pathname. The default is `node-gyp`.

v. 1.21.0

Installation§

Prerequisites§

Official Packages§

Amazon Linux§

CentOS§

Debian§

Fedora§

RHEL§

Ubuntu§

Homebrew§

Go§

Node.js§

Startup and Shutdown§

Community Repositories§

Docker Images§

Initial Configuration§

Source Code§

Obtaining Sources§

Installing Required Software§

Configuring Sources§

Directory Structure§

Configuring Modules§

Building and Installing Unit§

Embedded Language Modules§

External Language Modules§

Startup§

`--config=pathname`	Pathname of the php-config script invoked to configure the PHP module. The default is `php-config`.
`--lib-path=directory`	Directory path of PHP’s embed SAPI library file (`libphp<version>.so` or `.a`).
`--lib-static`	Links the static embed SAPI library (`libphp<version>.a`) instead of the dynamic one (`libphp<version>.so`); requires `--lib-path`.
`--module=filename`	Name of the module to be built (`<module>.unit.so`), also used in make targets. The default is `--config`’s filename minus the -config suffix; thus, `/path/php7-config` turns into `php7`.

`--help`, `-h`	Displays a summary of Unit’s command-line options and their default values set at compile time.
`--no-daemon`	Runs Unit in non-daemon mode.
`--version`	Displays Unit’s version and the ./configure settings it was built with.
`--control socket`	Control API socket address in IPv4, IPv6, or Unix (with `unix:` prefix) domain format: # unitd --control unix:/path/to/control.unit.sock # unitd --control 127.0.0.1:8080 # unitd --control [::1]:8080
`--group name`, `--user name`	Group name and user name used to run Unit’s non-privileged processes.
`--log pathname`	Pathname for the Unit log.
`--modules directory`	Directory path for Unit language modules (`<module>.unit.so` files).
`--pid pathname`	Pathname for the PID file of Unit’s main process.
`--state directory`	Directory path for Unit state storage.