Backend Development 8 min read

Master NGINX Unit: Install, Configure, and Run Multi‑Language Apps

This guide introduces NGINX Unit, a lightweight dynamic web and application server supporting multiple languages, and provides step‑by‑step installation instructions for CentOS, Ubuntu, and Docker, along with configuration examples for PHP and Java applications using its RESTful JSON API.

Ops Development Stories

Nov 24, 2020

Master NGINX Unit: Install, Configure, and Run Multi‑Language Apps

NGINX Unit is a dynamic web and application server that can run applications written in many programming languages. It is lightweight, supports multiple languages, and can be reconfigured at runtime via a RESTful JSON API.

Key Features

Dynamic configuration through a RESTful JSON API

Zero‑downtime configuration updates

Regex‑based request routing

Multiple language and version deployments simultaneously

Dynamic load balancing

Common language API for supported languages

Supported Languages

Assembly (via embedded libunit library)

Go (by overloading the http module)

JavaScript/Node.js (by overloading http and websocket modules)

Java (via Servlet Specification 3.1 and WebSocket APIs)

Perl (via PSGI)

PHP (via the embed SAPI)

Python (via WSGI and ASGI with WebSocket support)

Ruby (via the Rack API)

Installation

CentOS

Add the yum repository:

<code>cat >> /etc/yum.repos.d/unit.repo <<EOF
[unit]
name=unit repo
baseurl=https://packages.nginx.org/unit/centos/$releasever/$basearch/
gpgcheck=0
enabled=1
EOF</code>

Install Unit and language modules:

<code>sudo yum install unit
sudo yum install unit-devel unit-go unit-jsc8 unit-jsc11 \
      unit-perl unit-php unit-python27 unit-python36</code>

Start and enable the service:

<code>systemctl start unit
systemctl enable unit</code>

Socket location:

/var/run/unit/control.sock

Log location:

/var/log/unit/unit.log

Ubuntu

Import the signing key:

<code>sudo curl -sL https://nginx.org/keys/nginx_signing.key | sudo apt-key add -</code>

Add the repository:

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

Install Unit and language modules:

<code>sudo apt update
sudo apt install unit
sudo apt install unit-dev unit-go unit-jsc11 unit-jsc13 unit-jsc14 unit-jsc15 \
      unit-perl unit-php unit-python3.8 unit-ruby</code>

Socket location:

/var/run/unit/control.sock

Log location:

/var/log/unit/unit.log

Docker

Run the official Docker image:

<code>docker pull nginx/unit
docker run -d nginx/unit</code>

Usage

PHP Example

Create a directory and an

index.php

file:

<code>mkdir /opt/php
cat >> /opt/php/index.php <<EOF
<html>
<head>
<title>PHP Test</title>
</head>
<body>
<?php echo '<p>Hello World，Joker is coming.</p>'; ?>
</body>
</html>
EOF</code>

Create a configuration file

php.json

<code>cat >> php.json <<EOF
{
    "listeners": {
        "0.0.0.0:8300": {
            "pass": "applications/blogs"
        }
    },
    "applications": {
        "blogs": {
            "type": "php",
            "root": "/opt/php"
        }
    }
}
EOF</code>

Apply the configuration via the control socket:

<code>curl -X PUT -d @php.json --unix-socket /var/run/unit/control.sock http://localhost/config/</code>

Successful response:

<code>{
    "success": "Reconfiguration done."
}</code>

Access the application in a browser at

http://IP:8300

View the current configuration:

<code>curl --unix-socket /var/run/unit/control.sock http://localhost/config/</code>

Delete the application configuration:

<code>curl -X DELETE -d @php.json --unix-socket /var/run/unit/control.sock http://localhost/config/</code>

Java Example

Create a directory and an

index.jsp

file:

<code>mkdir /opt/java
cat >> /opt/java/index.jsp <<EOF
<%@ page language="java" contentType="text/plain" %>
<%= "Hello, JSP on Unit!" %>
EOF</code>

Create a configuration file

java.json

<code>cat >> java.json <<EOF
{
    "listeners": {
        "0.0.0.0:8400": {
            "pass": "applications/myapp"
        }
    },
    "applications": {
        "myapp": {
            "type": "java",
            "webapp": "/opt/java/"
        }
    }
}
EOF</code>

Apply the configuration:

<code># curl -X PUT -d @java.json --unix-socket /var/run/unit/control.sock http://localhost/config/
{
    "success": "Reconfiguration done."
}</code>

Open a browser at

http://IP:8400

to see the Java response:

Conclusion

NGINX Unit is a powerful and versatile project that supports many languages. While its API‑driven configuration offers great flexibility, the learning curve can be steep and the all‑API approach may feel cumbersome for some users.

backend Java configuration php web server installation nginx-unit

Written by

Ops Development Stories

Maintained by a like‑minded team, covering both operations and development. Topics span Linux ops, DevOps toolchain, Kubernetes containerization, monitoring, log collection, network security, and Python or Go development. Team members: Qiao Ke, wanger, Dong Ge, Su Xin, Hua Zai, Zheng Ge, Teacher Xia.

0 followers

Reader feedback

How this landed with the community

Rate this article

Was this worth your time?

Discussion

0 Comments

Thoughtful readers leave field notes, pushback, and hard-won operational detail here.