Building From Source§
After you’ve obtained Unit’s source code, configure and compile it to fine-tune and run a custom Unit build.
Installing Required Software§
Before configuring and compiling Unit, install the required build tools and the library files for the supported languages (Go, Java, Node.js, PHP, Perl, Python, and Ruby), plus 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 COMPILE-TIME 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-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 |
--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 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-regex |
Turns off regex support; any attempts to use a regex in Unit configuration will fail. |
--no-pcre2 |
Skips 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=directory , --sbindir=directory |
Directory paths for end-user and sysadmin executables. The defaults are |
--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 |
--incdir=directory , --libdir=directory |
Directory paths for libunit header files and libraries. The defaults are |
--mandir=directory |
Directory path where the The default is |
--log=pathname |
Pathname for Unit’s log. The default is |
--modules=directory |
Directory path for Unit’s language modules. The default is |
--pid=pathname |
Pathname for the PID file of Unit’s main process. The default is |
--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
The default is |
--tmp=directory |
Defines the temporary file storage location (used to dump large request bodies). The default value is |
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:
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/
.For further packaging or containerization, specify
DESTDIR
at installation to place the files in a staging location while preserving their relative structure. Otherwise, omitDESTDIR
for direct installation.
An alternative scenario is a build that you can move around the file system:
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/
.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. To package custom modules, see the module howto.
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-path=directory |
Custom directory path for Go package installation. The default is |
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 |
--jars=directory |
Directory path for Unit’s custom The default is the Java module path. |
--lib-path=directory |
Directory path for the The default is based on JDK settings. |
--local-repo=directory |
Directory path for local The default is |
--repo=directory |
URL path for remote Maven repository. The default is |
--module=basename |
Name of the module to be built ( The default is |
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 |
--npm=pathname |
Specific NPM executable pathname. The default is |
--node-gyp=pathname |
Specific node-gyp executable pathname. The default is |
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 |
--module=basename |
Name of the module to be built ( The default is the filename of the |
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 |
--lib-path=directory |
Directory path of the libphp library file
( $ php-config --php-sapis
... embed ...
|
--lib-static |
Links 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 ( The default is |
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 |
--lib-path=directory |
Custom directory path of the Python runtime library to use with Unit. |
--module=basename |
Name of the module to be built ( The default is |
Note
The Python interpreter set by python-config must be
compiled with the --enable-shared
option.
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 ( The default is the filename of the |
--ruby=pathname |
Specific Ruby executable pathname. The default is |
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 RUNTIME OPTIONS
Otherwise, start unitd from the sbin
subdirectory relative
to installation directory prefix:
# cd /path/to/unit/
# sbin/unitd RUNTIME OPTIONS
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 , -h |
Displays a summary of Unit’s command-line options and their compile-time defaults. |
--version |
Displays Unit’s version and the ./configure settings it was built with. |
--no-daemon |
Runs 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 name |
Group name and user name used to run Unit’s non-privileged processes. |
--log pathname |
Pathname for Unit’s log. |
--modules directory |
Directory path for Unit’s language modules
(*.unit.so files). |
--pid pathname |
Pathname for the PID file of Unit’s main process. |
--state directory |
Directory path for Unit’s state storage. |
--tmp directory |
Directory 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.