NGINX Unit
v. 1.24.0

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

Official Packages§

Installing a precompiled Unit binary package is best for most occasions; official binaries are available for:

  • Amazon Linux, Amazon Linux 2
  • CentOS 6, 7, 8
  • Debian 9, 10
  • Fedora 29, 30, 31, 32, 33
  • RHEL 6, 7, 8
  • Ubuntu 16.04, 18.04, 19.10, 20.04, 20.10, 21.04

The packages we provide include core executables, developer files, and support for individual languages. We also maintain an official Homebrew tap for macOS users.

Note

Unit’s language module for Node.js is available at the npm registry.

Note

For details of packaging custom modules that install alongside the official Unit, see here.

Amazon Linux§

Supported architectures: x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

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

  2. Install the core package and other packages you need:

    # yum install unit
# yum install unit-devel unit-go unit-jsc8 unit-perl \
      unit-php unit-python27 unit-python37

Warning

Unit’s 1.22+ packages aren’t available for Amazon Linux AMI. This distribution is obsolete; please update.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

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

  2. Install the core package and other packages you need:

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

Note

Control socket’s pathname: /var/run/unit/control.sock; log file’s pathname: /var/log/unit/unit.log; non-privileged process accounts: unit:unit.

CentOS§

Supported architectures: x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

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

  2. Install the core package and other packages you need:

    # yum install unit
# yum install unit-devel unit-go unit-jsc8 unit-jsc11 \
      unit-perl unit-php unit-python27 unit-python36

Warning

Unit’s 1.20+ packages aren’t available for CentOS 6. This distribution is obsolete; please update.

Supported architectures: i386, x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

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

  2. Install the core package and other packages you need:

    # yum install unit
# yum install unit-devel unit-go unit-jsc8 unit-php unit-python

Note

Control socket’s pathname: /var/run/unit/control.sock; log file’s pathname: /var/log/unit/unit.log; non-privileged process accounts: unit:unit.

Debian§

Supported architectures: i386, x86-64.

  1. Download NGINX’s signing key and add it to apt’s keyring:

    # curl -sL https://nginx.org/keys/nginx_signing.key | apt-key add -

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

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

  3. Install the core package and other packages you need:

    # apt update
# apt install unit
# apt install unit-dev unit-go unit-jsc11 unit-perl \
      unit-php unit-python2.7 unit-python3.7 unit-ruby

Warning

Unit’s 1.22+ packages aren’t available for Debian 9.

  1. Download NGINX’s signing key and add it to apt’s keyring:

    # curl -sL https://nginx.org/keys/nginx_signing.key | apt-key add -

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

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

  3. Install the core package and other packages you need:

    # apt update
# apt install unit
# apt install unit-dev unit-go unit-jsc8 unit-perl \
      unit-php unit-python2.7 unit-python3.5 unit-ruby

Note

Control socket’s pathname: /var/run/control.unit.sock; log file’s pathname: /var/log/unit.log; non-privileged process accounts: unit:unit.

Fedora§

Supported architectures: x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

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

  2. Install the core package and other packages you need:

    # yum install unit
# yum install unit-devel unit-go unit-jsc11 unit-jsc8 unit-perl \
      unit-php unit-python39 unit-ruby

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

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

  2. Install the core package and other packages you need:

    # yum install unit
# yum install unit-devel unit-go unit-jsc11 unit-jsc8 unit-perl \
      unit-php unit-python38 unit-ruby

Warning

Unit’s 1.20+ packages aren’t available for Fedora 30; 1.22+ packages aren’t available for Fedora 31. These distributions are obsolete; please update.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

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

  2. Install the core package and other packages you need:

    # yum install unit
# yum install unit-devel unit-go unit-jsc11 unit-jsc8 unit-perl \
      unit-php unit-python27 unit-python37 unit-ruby

Warning

Unit’s 1.20+ packages aren’t available for Fedora 29. This distribution is obsolete; please update.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

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

  2. Install the core package and other packages you need:

    # yum install unit
# yum install unit-devel unit-go unit-jsc8 unit-perl \
      unit-php unit-python27 unit-python37 unit-ruby

Note

Control socket’s pathname: /var/run/unit/control.sock; log file’s pathname: /var/log/unit/unit.log; non-privileged process accounts: unit:unit.

RHEL§

Supported architectures: x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

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

  2. Install the core package and other packages you need:

    # yum install unit
# yum install unit-devel unit-go unit-jsc8 unit-jsc11 \
      unit-perl unit-php unit-python27 unit-python36

Warning

Unit’s 1.20+ packages aren’t available for RHEL 6. This distribution is obsolete; please update.

Supported architectures: i386, x86-64.

  1. To configure Unit’s repository, create the following file named /etc/yum.repos.d/unit.repo:

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

  2. Install the core package and additional packages you need:

    # yum install unit
# yum install unit-devel unit-go unit-jsc8 unit-perl \
      unit-php unit-python

Note

Control socket’s pathname: /var/run/unit/control.sock; log file’s pathname: /var/log/unit/unit.log; non-privileged process accounts: unit:unit.

Ubuntu§

Supported architectures: arm64, x86-64.

  1. Download NGINX’s signing key and add it to apt’s keyring:

    # curl -sL https://nginx.org/keys/nginx_signing.key | apt-key add -

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

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

  3. Install the core package and other packages you need:

    # apt update
# apt install unit
# apt install unit-dev unit-go unit-jsc11 unit-jsc15 unit-jsc16 unit-jsc17 \
              unit-perl unit-php unit-python2.7 unit-python3.9 unit-ruby

Supported architectures: arm64, x86-64.

  1. Download NGINX’s signing key and add it to apt’s keyring:

    # curl -sL https://nginx.org/keys/nginx_signing.key | apt-key add -

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

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

  3. Install the core package and other packages you need:

    # apt update
# apt install unit
# apt install unit-dev unit-go unit-jsc11 unit-jsc13 unit-jsc14 unit-jsc15 \
              unit-perl unit-php unit-python3.8 unit-ruby

Supported architectures: arm64, x86-64.

  1. Download NGINX’s signing key and add it to apt’s keyring:

    # curl -sL https://nginx.org/keys/nginx_signing.key | apt-key add -

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

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

  3. Install the core package and other packages you need:

    # apt update
# apt install unit
# apt install unit-dev unit-go unit-jsc11 unit-perl \
      unit-php unit-python2.7 unit-python3.8 unit-ruby

Warning

Unit’s 1.20+ packages aren’t available for Ubuntu 19.10. This distribution is obsolete; please update.

Supported architectures: x86-64.

  1. Download NGINX’s signing key and add it to apt’s keyring:

    # curl -sL https://nginx.org/keys/nginx_signing.key | apt-key add -

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

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

  3. Install the core package and other packages you need:

    # apt update
# apt install unit
# apt install unit-dev unit-go unit-jsc11 unit-perl \
      unit-php unit-python2.7 unit-python3.7 unit-python3.8 unit-ruby

Supported architectures: arm64, x86-64.

  1. Download NGINX’s signing key and add it to apt’s keyring:

    # curl -sL https://nginx.org/keys/nginx_signing.key | apt-key add -

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

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

  3. Install the core package and other packages you need:

    # apt update
# apt install unit
# apt install unit-dev unit-go unit-jsc8 unit-jsc11 unit-perl \
      unit-php unit-python2.7 unit-python3.6 unit-python3.7 unit-ruby

Warning

Unit’s 1.24+ packages aren’t available for Ubuntu 16.04. This distribution is obsolete; please update.

Supported architectures: arm64, i386, x86-64.

  1. Download NGINX’s signing key and add it to apt’s keyring:

    # curl -sL https://nginx.org/keys/nginx_signing.key | apt-key add -

    This eliminates the packages cannot be authenticated warnings during installation.

  2. To configure Unit’s repository, create the following file named /etc/apt/sources.list.d/unit.list:

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

  3. Install the core package and other packages you need:

    # apt update
# apt install unit
# apt install unit-dev unit-go unit-jsc8 unit-perl unit-php \
      unit-python2.7 unit-python3.5 unit-ruby

Note

Control socket’s pathname: /var/run/control.unit.sock; log file’s pathname: /var/log/unit.log; non-privileged process accounts: unit:unit.

Homebrew§

To install Unit on macOS from our official Homebrew tap:

$ brew install nginx/unit/unit

This deploys the core Unit binary and the prerequisites for Go and Node.js language module installation.

To install the Java, Perl, Python, and Ruby language modules from Homebrew:

$ brew install unit-java unit-perl unit-python unit-python3 unit-ruby

Note

Control socket’s pathname: /usr/local/var/run/unit/control.sock; log file’s pathname: /usr/local/var/log/unit/unit.log.

Go§

To install the Go package for Unit, use the official packages or run:

$ go get unit.nginx.org/go

That’s it; now, you can use it to run your Go apps on Unit.

Node.js§

Unit’s npm-hosted Node.js module is called unit-http; installing it is necessary to run Node.js apps on Unit:

  1. First, install the unit-dev/unit-devel package, necessary to build unit-http.

  2. Next, build and install unit-http globally (this step requires npm and node-gyp):

    # npm install -g --unsafe-perm unit-http

    Warning

    The unit-http module is platform dependent due to optimizations; you can’t move it across systems with the rest of node-modules. Global installation avoids such scenarios; just relink the migrated app.

  3. It’s entirely possible to run Node.js apps on Unit without mentioning unit-http in your app sources. However, you can explicitly use unit-http in your code instead of the built-in http, but mind that such frameworks as Express may require extra changes.

If you update Unit later, make sure to update the module as well:

# npm update -g --unsafe-perm unit-http

Note

You can also configure and install the unit-http module from sources.

Startup and Shutdown§

Run unitd -h or unitd --version to verify Unit is available or list its settings. To manage the installation:

Enable Unit to launch automatically at system startup:

# systemctl enable unit

Start or restart Unit:

# systemctl restart unit

Stop a running Unit:

# systemctl stop unit

Disable Unit’s automatic startup:

# systemctl disable unit

Start Unit as a daemon:

# unitd

Stop all Unit’s processes:

# pkill unitd

For startup options, see below.

Community Repositories§

Warning

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

To install Unit’s core 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 and groupunit
Startup and shutdown
# service unit enable
# service unit restart
# service unit stop
# service unit disable

To install Unit’s core executables and specific language modules from the Sisyphus packages:

# apt-get update
# apt-get install unit
# apt-get install unit-perl unit-php unit-ruby

Runtime details:

Control socket/run/unit/control.sock
Log file/var/log/unit/unit.log
Non-privileged user and group_unit (mind the _ prefix)
Startup and shutdown
# service unit enable
# service unit restart
# service unit stop
# service unit disable

To install Unit’s core 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 and groupnobody
Startup and shutdown
# systemctl enable unit
# systemctl restart unit
# systemctl stop unit
# systemctl disable unit

If you use SCLo Software Collections, 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

Runtime details: see CentOS, RHEL, and Startup and Shutdown.

To install Unit from FreeBSD packages, get 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-php73 unit-php74 unit-php80  \
                 unit-python37  \
                 unit-ruby2.7

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 and groupwww
Startup and shutdown
# service unitd enable
# service unitd restart
# service unitd stop
# service unitd disable

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 and groupnobody
Startup and shutdown
# rc-update add nginx-unit
# rc-service nginx-unit restart
# rc-service nginx-unit stop
# rc-update del nginx-unit

To install Unit’s core package and the other packages you need from the NetBSD Package Collection:

# pkg_add unit
# pkg_add libunit
# pkg_add unit-perl  \
          unit-python2.7  \
          unit-python3.6 unit-python3.7 unit-python3.8 unit-python3.9

To build Unit manually, start by updating the package collection:

# cd /usr/pkgsrc && cvs update -dP

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

# cd /usr/pkgsrc/www/unit/
# make build install

Repeat the steps for the other packages you need: libunit (required to install the Node.js module and build Go apps), 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 and groupunit
Startup and shutdown

First, add Unit’s startup script to the /etc/rc.d/ directory:

# cp /usr/pkg/share/examples/rc.d/unit /etc/rc.d/

After that, you can start and stop Unit as follows:

# service unit restart
# service unit stop

To enable or disable Unit’s automatic startup, edit /etc/rc.conf:

# Enable service:
unit=YES

# Disable service:
unit=NO

To install Unit’s core 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; for a .nix configuration file defining an app, see this sample.

Runtime details:

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

Add services.unit.enable = true; to /etc/nixos/configuration.nix and rebuild the system configuration:

# nixos-rebuild switch

After that, use systemctl:

# systemctl enable unit
# systemctl restart unit
# systemctl stop unit
# systemctl disable unit

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’s 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 and groupnobody
Startup and shutdown
# systemctl enable unit
# systemctl restart unit
# systemctl stop unit
# systemctl disable unit

Docker Images§

Unit’s Docker images come in several language-specific flavors:

TagDescription
|version|-minimalNo language modules are included.
|version|-go1.15Single-language image based on the golang:1.15 image.
|version|-jsc11Single-language image based on the openjdk:11-jdk image.
|version|-node15Single-language image based on the node:15 image.
|version|-perl5.32Single-language image based on the perl:5.32 image.
|version|-php8.0Single-language image based on the php:8.0-cli image.
|version|-python3.9Single-language image based on the python:3.9 image.
|version|-ruby2.7Single-language image based on the ruby:2.7 image.
Customizing Language Versions in Docker Images

To create a Unit image with a different language version, clone the sources and rebuild them locally on a machine with Docker installed. The build command has the following format:

$ make build-<language name><language version> VERSION_<language name>=<language version>

The make utility parses the command line to extract the language name and version; these values must reference an existing official language image to be used as the base for the build. If not sure whether an official image exists for a specific language version, follow the links in the tag table above.

The language name can be go, jsc, node, perl, php, python, or ruby; the version is defined as <major>.<minor>, except for jsc and node that take only major version numbers (as exemplified by the tag table). Thus, to create a local image based on Python 3.6 and tagged as unit:|version|-python3.6:

$ git clone https://github.com/nginx/unit
$ cd unit
$ git checkout 1.24.0  # Optional; use to choose a specific Unit version
$ cd pkg/docker/
$ make build-python3.6 VERSION_python=3.6

For details, see the Makefile. For other customization scenarios, see our Howto.

Images With Pre-1.22.0 Unit Versions

Before Unit 1.22.0 was released, the following tagging scheme was used:

TagDescription
<version>-fullContains modules for all languages that Unit currently supports.
<version>-minimalNo language modules are included.
<version>-<language>A specific language module such as 1.21.0-ruby2.3 or 1.21.0-python2.7.

You can obtain the images from these sources:

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

$ docker pull docker.io/nginx/unit:TAG
$ docker run -d docker.io/nginx/unit:TAG

To install and run Unit from NGINX’s repository at Amazon ECR Public Gallery:

$ docker pull public.ecr.aws/nginx/unit:TAG
$ docker run -d public.ecr.aws/nginx/unit:TAG

To install and run Unit from tarballs stored on our website:

$ curl -O https://packages.nginx.org/unit/docker/1.24.0/nginx-unit-TAG.tar.gz
$ curl -O https://packages.nginx.org/unit/docker/1.24.0/nginx-unit-TAG.tar.gz.sha512
$ sha512sum -c nginx-unit-TAG.tar.gz.sha512
      nginx-unit-TAG.tar.gz: OK

$ docker load < nginx-unit-TAG.tar.gz

Note

Control socket’s pathname: /var/run/control.unit.sock; log file’s pathname: forwarded to the Docker log collector; non-privileged process accounts: unit:unit.

For more details, see the repository pages (Docker Hub, Amazon ECR Public Gallery) and our 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 TypePurpose/Action
.pemCertificate bundles are uploaded under respective names: cert.pem to certificates/cert.
.jsonConfiguration snippets are uploaded as to the config section of Unit’s configuration.
.shShell 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.24.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:1.24.0-minimal)

Source Code§

Obtaining Sources§

You can get Unit’s source code from our official Mercurial repository, its GitHub mirror, or in a tarball.

If you’d like to use Mercurial:

$ hg clone https://hg.nginx.org/unit
$ cd unit

If you prefer Git:

$ git clone https://github.com/nginx/unit
$ cd unit

To download sources directly from our site:

$ curl -O https://unit.nginx.org/download/unit-1.24.0.tar.gz
$ tar xzf unit-1.24.0.tar.gz
$ cd unit-1.24.0

Installing Required Software§

Before configuring and compiling Unit, install the required build tools plus the library files for the supported languages (Go, Java, Node.js, PHP, Perl, Python, and Ruby), and other features you want to use with Unit.

The commands below assume you are configuring Unit with all supported languages and features (X, Y, and Z stand in for major, minor, and revision numbers, respectively); omit the packages you won’t use.

# apt install build-essential
# apt install golang
# curl -sL https://deb.nodesource.com/setup_X.Y | bash -
# apt install nodejs
# npm install -g node-gyp
# apt install php-dev libphp-embed
# apt install libperl-dev
# apt install python-dev
# apt install ruby-dev
# apt install openjdk-X-jdk
# apt install libssl-dev
# apt install libpcre2-dev

# yum install gcc make
# yum install golang
# curl -sL https://rpm.nodesource.com/setup_X.Y | bash -
# yum install nodejs
# npm install -g node-gyp
# yum install php-devel php-embedded
# yum install perl-devel perl-libs
# yum install python-devel
# yum install ruby-devel
# yum install java-X.Y.Z-openjdk-devel
# yum install openssl-devel
# yum install pcre2-devel

Ports:

# cd /usr/ports/lang/go/ && make install clean
# cd /usr/ports/www/node/ && make install clean
# cd /usr/ports/www/npm/ && make install clean && npm i -g node-gyp
# cd /usr/ports/lang/phpXY/ && make install clean
# cd /usr/ports/lang/perlX.Y/ && make install clean
# cd /usr/ports/lang/python/ && make install clean
# cd /usr/ports/lang/rubyXY/ && make install clean
# cd /usr/ports/java/openjdkX/ && make install clean
# cd /usr/ports/security/openssl/ && make install clean
# cd /usr/ports/devel/pcre2/ && make install clean

Packages:

# pkg install go
# pkg install node && pkg install npm && npm i -g node-gyp
# pkg install phpXY
# pkg install perlX
# pkg install python
# pkg install rubyXY
# pkg install openjdkX
# pkg install openssl
# pkg install pcre2

# pkg install gcc
# pkg install golang
# pkg install php-XY
# pkg install ruby
# pkg install jdk-X
# pkg install openssl
# pkg install pcre

Also, use gmake instead of make when building and installing Unit on Solaris.

Configuring Sources§

To run system compatibility checks and generate a Makefile with core build instructions for Unit:

$ ./configure <command-line options>

To finalize the resulting Makefile, configure the language modules you need.

General options and settings that control compilation, runtime privileges, or support for certain features:

--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=optionsExtra 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.

--debugTurns on the debug log.
--no-ipv6Turns off IPv6 support.
--no-unix-socketsTurns 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 Certificate Management.

By default, Unit relies on the installed version of the PCRE library to support regular expressions in routes; if both major versions are present, Unit selects PCRE2. Two additional flags alter this behavior:

--no-regexTurns off regex support; any attempts to use a regex in Unit configuration will fail.
--no-pcre2Skips the PCRE2 library; the older PCRE 8.x library is used instead.

The next option group customizes Unit’s runtime directory structure:

--prefix=prefix

Destination directory prefix for path options: --bindir, --sbindir, --libdir, --incdir, --mandir, --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=127.0.0.1:8080
$ ./configure --control=[::1]:8080
$ ./configure --control=unix:/path/to/control.unit.sock

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.

--mandir=directory

Directory path where the unitd(8) man page is installed.

The default is share/man.

--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 main 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 file storage location (used to dump large request bodies).

The default value is tmp.

Directory Structure§

To customize Unit’s installation and runtime directories, you can both:

  • Set the --prefix and path options (their relative settings are prefix-based) during configuration to set up the runtime file structure: Unit uses these settings to locate its modules, state, and other files.
  • Set the DESTDIR variable during installation. Unit’s file structure is placed at the specified directory, which can be either the final installation target or an intermediate staging location.

Coordinate these two options as necessary to customize the directory structure. One common scenario is installation based on absolute paths:

  1. Set absolute runtime paths with --prefix and path options:

    $ ./configure --state=/var/lib/unit --log=/var/log/unit.log \
              --control=unix:/run/control.unit.sock --prefix=/usr/local/

    Configured thus, Unit will store its state, log, and control socket at custom locations; other files will have default prefix-based paths. Here, unitd is put to /usr/local/sbin/, modules to /usr/local/modules/.

  2. For further packaging or containerization, specify DESTDIR at installation to place the files in a staging location while preserving their relative structure. Otherwise, omit DESTDIR for direct installation.

An alternative scenario is a build that you can move around the filesystem:

  1. Set relative runtime paths with --prefix and path options:

    $ ./configure --state=config --log=log/unit.log \
              --control=unix:control/control.unit.sock --prefix=movable

    Configured this way, Unit will store its files by prefix-based paths (both default and custom), for example, <working directory>/movable/sbin/ or <working directory>/movable/config/.

  2. Specify DESTDIR when installing the build. You can migrate such builds if needed; move the entire file structure and launch binaries from the base directory so that the relative paths stay valid:

    $ cd DESTDIR
# movable/sbin/unitd

You can combine these approaches, but take care to understand how your settings work together.

Configuring Modules§

Next, configure a module for each language you want to use with Unit. The ./configure <language> commands set up individual language modules and place module-specific instructions in the Makefile.

Note

To run apps in several versions of a language, build and install a module for each version.

When you run ./configure go, Unit sets up the Go package that lets your applications run on Unit. To use the package, install it in your Go environment. Available configuration options:

--go=pathname

Specific Go executable pathname, also used in make targets.

The default is go.

--go-path=directory

Custom directory path for Go package installation.

The default is $GOPATH.

Note

The ./configure script doesn’t alter the GOPATH environment variable. The two paths (configuration-time --go-path and compile-time GOPATH) must be coherent at build time for Go to locate the Unit package.

When you run ./configure java, the script configures a module to support running Java Web Applications on Unit. Available command options:

--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=basename

Name of the module to be built (<basename>.unit.so), also used in make targets.

The default is java.

To configure a module called java11.unit.so with OpenJDK 11.0.1:

$ ./configure java --module=java11 \
                   --home=/Library/Java/JavaVirtualMachines/jdk-11.0.1.jdk/Contents/Home

When you run ./configure nodejs, Unit sets up the unit-http module that lets your applications run on Unit. Available configuration options:

--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.

When you run ./configure perl, the script configures a module to support running Perl scripts as applications on Unit. Available command options:

--perl=pathname

Specific Perl executable pathname.

The default is perl.

--module=basename

Name of the module to be built (<basename>.unit.so), also used in make targets.

The default is the filename of the --perl executable.

To configure a module called perl-5.20.unit.so for Perl 5.20.2:

$ ./configure perl --module=perl-5.20 \
                   --perl=perl5.20.2

When you run ./configure php, the script configures a custom SAPI module linked with the libphp library to support running PHP applications on Unit. Available command options:

--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 the libphp library file (libphp*.so or libphp*.a), usually available with an --enable-embed PHP build:

$ php-config --php-sapis

      ... embed ...
--lib-staticLinks the static libphp library (libphp*.a) instead of the dynamic one (libphp*.so); requires --lib-path.
--module=basename

Name of the module to be built (<basename>.unit.so), also used in make targets.

The default is --config’s filename minus the -config suffix; thus, /path/php7-config turns into php7.

To configure 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

When you run ./configure python, the script configures a module to support running Python scripts as applications on Unit. Available command options:

--config=pathname

Pathname of the python-config script invoked to configure the Python module.

The default is python-config.

--lib-path=directoryCustom directory path of the Python runtime library to use with Unit.
--module=basename

Name of the module to be built (<basename>.unit.so), also used in make targets.

The default is --config’s filename minus the -config suffix; thus, /path/python3-config turns into python3.

To configure a module called py33.unit.so for Python 3.3:

$ ./configure python --module=py33 \
                     --config=python-config-3.3

When you run ./configure ruby, the script configures a module to support running Ruby scripts as applications on Unit. Available command options:

--module=basename

Name of the module to be built (<basename>.unit.so), also used in make targets.

The default is the filename of the --ruby executable.

--ruby=pathname

Specific Ruby executable pathname.

The default is ruby.

To configure a module called ru23.unit.so for Ruby 2.3:

$ ./configure ruby --module=ru23 \
                   --ruby=ruby23

Building and Installing Unit§

To build and install Unit’s executables and language modules that you have ./configure’d earlier:

$ make
# make install

You can also build and install language modules individually; the specific method depends on whether the language module is embedded in Unit or packaged externally.

Note

For further details about Unit’s language modules, see Working With Language Modules.

Embedded Language Modules§

To build and install the modules for Java, PHP, Perl, Python, or Ruby after configuration, run make <module basename> and make <module basename>-install, for example:

$ make perl-5.20
# make perl-5.20-install

External Language Modules§

To build and install the modules for Go and Node.js globally after configuration, run make <go>-install and make <node>-install, for example:

# make go-install
# make node-install

Note

To install the Node.js module locally, run make <node>-local-install:

# make node-local-install

If you haven’t specified the --local directory with ./configure nodejs earlier, provide it here: DESTDIR=/your/project/directory. If both options are specified, DESTDIR prefixes the --local value.

However, mind that global installation is the recommended method for the Node.js module.

If you customize the executable pathname with --go or --node, use the following pattern:

$ ./configure nodejs --node=/usr/local/bin/node8.12
# make /usr/local/bin/node8.12-install

$ ./configure go --go=/usr/local/bin/go1.7
# make /usr/local/bin/go1.7-install

Startup and Shutdown§

Warning

We advise installing Unit from precompiled packages; in this case, startup is configured automatically.

Even if you install Unit otherwise, avoid manual startup. Instead, configure a service manager such as OpenRC or systemd or create an rc.d script to launch the Unit daemon using the options below.

The startup command depends on your ./configure options. If you have configured absolute paths:

# unitd

Otherwise, start unitd from the sbin subdirectory relative to installation directory prefix:

# cd /path/to/unit/
# sbin/unitd

Run unitd -h or unitd --version to list Unit’s compile-time settings. Usually, the defaults don’t require overrides; however, the following runtime options are available. For details and security notes, see here.

General runtime options and compile-time setting overrides:

--help, -hDisplays a summary of Unit’s command-line options and their compile-time defaults.
--versionDisplays Unit’s version and the ./configure settings it was built with.
--no-daemonRuns Unit in non-daemon mode.
--control socket

Control API socket address in IPv4, IPv6, or Unix domain format:

# unitd --control 127.0.0.1:8080
# unitd --control [::1]:8080
# unitd --control unix:/path/to/control.unit.sock
--group name, --user nameGroup name and user name used to run Unit’s non-privileged processes.
--log pathnamePathname for Unit’s log.
--modules directoryDirectory path for Unit’s language modules (*.unit.so files).
--pid pathnamePathname for the PID file of Unit’s main process.
--state directoryDirectory path for Unit’s state storage.
--tmp directoryDirectory path for Unit’s temporary file storage.

Finally, to stop a running Unit:

# pkill unitd

This command signals all Unit’s processes to terminate in a graceful manner.

Improve this page