DOCSEARCHbyAlgolia
Submit Docs

NGINX Unit Documentation

repository·master·Indexed 26 days ago

https://github.com/nginx/unit

A lightweight, high-performance universal web application server that serves static assets and runs application code in Python, PHP, Node.js, Ruby, and WebAssembly. Features a RESTful JSON API for dynamic, zero-interruption configuration. Includes documentation for installation via Docker, Homebrew, and Linux package managers, as well as management tools like unitc and unitctl.

Tokens
9.1K
Snippets
18
Records
81
Agent score
91%

What's inside NGINX Unit

  1. Use unitctl and the NGINX Unit Rust SDK

    master
    The unitctl project provides both a CLI tool and a Rust SDK for interacting with the NGINX Unit control API. The CLI (unitctl) exposes the same functionality provided by the Rust SDK.

  2. Install the `unitctl` CLI tool

    master

    If you did not install Unit via Homebrew (which includes unitctl by default), you can download the binary from the official GitHub releases. Extract the archive and move the binary to your PATH.

    $ tar xzvf unitctl-master-x86_64-unknown-linux-gnu.tar.gz
# mv unitctl /usr/local/bin/

  3. Install NGINX Unit on Debian, Ubuntu, Amazon Linux, Fedora, or Red Hat

    master

    First, use the setup-unit helper script to configure the correct package repositories for your system. Then, use your system's package manager to install unit.

    $ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit && chmod +x setup-unit
# ./setup-unit repo-config

# For Debian derivatives:
# apt install unit

# For Fedora derivatives:
# yum install unit

  4. Install NGINX Unit using Docker

    master

    You can run NGINX Unit using official Docker images. When running via Docker, your current working directory is mounted to /www inside the container. The control socket is typically located at /var/run/control.unit.sock inside the container, which can be exposed to the host via a bind mount.

    $ docker pull unit:<TAG>
$ mkdir /tmp/unit-control # customize as needed.
$ docker run -d \
      --mount type=bind,src=/tmp/unit-control,dst=/var/run \
      --mount type=bind,src=.,dst=/www \
      --network host \
      unit

  5. Run NGINX Unit fuzzers

    master

    After building the fuzzers, you can run them by providing a seed directory and a corpus directory. The following command pattern is used for the available fuzzers:

    ./build/<fuzzer_name> <seed_directory> <corpus_directory>

    Available fuzzers and their corresponding seed/corpus paths:

    • fuzz_basic
    • fuzz_http_controller
    • fuzz_http_h1p
    • fuzz_http_h1p_peer
    • fuzz_json
    # Create seed directories
mkdir -p build/fuzz_basic_seed
mkdir -p build/fuzz_http_controller_seed
mkdir -p build/fuzz_http_h1p_seed
mkdir -p build/fuzz_http_h1p_peer_seed
mkdir -p build/fuzz_json_seed

# Run the fuzzers
./build/fuzz_basic            build/fuzz_basic_seed            fuzzing/fuzz_basic_seed_corpus
./build/fuzz_http_controller  build/fuzz_http_controller_seed  fuzzing/fuzz_http_seed_corpus
./build/fuzz_http_h1p         build/fuzz_http_h1p_seed         fuzzing/fuzz_http_seed_corpus
./build/fuzz_http_h1p_peer    build/fuzz_http_h1p_peer_seed    fuzzing/fuzz_http_seed_corpus
./build/fuzz_json             build/fuzz_json_seed             fuzzing/fuzz_json_seed_corpus

  7. Configure a PHP application via the RESTful JSON API

    master
    You can configure NGINX Unit by sending JSON payloads to its control API via a Unix domain socket. To run a PHP app, you must first define an applications object and then reference it in a listeners object.

  9. Read the current NGINX Unit configuration from a Docker container

    master

    If NGINX Unit is running inside a Docker container, you can retrieve its current configuration by executing a curl command against the control API via the Unix socket located at /var/run/control.unit.sock. Replace <containerID> with your actual container ID.

    docker exec -ti <containerID> curl --unix-socket /var/run/control.unit.sock http://localhost/config

  10. Configure remote NGINX Unit instances with unitc

    master

    To manage a remote NGINX Unit instance, you must specify the control socket. You can do this by setting the UNIT_CTRL environment variable or by including the protocol in the command.

    Supported Protocols:

    • SSH: ssh://[user@]remote_host[:ssh_port]/path/to/control.socket (Recommended)
    • HTTP: http://remote_host:unit_control_port
    • Docker: docker://container_ID[/path/to/control.socket]

    Note: Using plaintext HTTP for remote configuration has security implications; SSH is the recommended method.

    # Using environment variable for SSH
export UNIT_CTRL=ssh://root@unithost/var/run/control.unit.sock
unitc /config/routes

# Using HTTP directly
unitc http://192.168.0.1:8080/status
UNIT_CTRL=http://192.168.0.1:8080 unitc /status

# Using Docker
unitc docker://d43251184c54 /config
UNIT_CTRL=docker://4d0431488982 unitc /status/requests/total

  11. Start a new Unit process via Docker

    master

    You can launch new Unit containers using unitctl instances new. You must provide three arguments:

    1. Control API access: A directory path (which will be mounted to /var/run internally to expose the unix socket) or a TCP endpoint (e.g., 127.0.0.1:7171).
    2. Application path: A host path to be mounted to /www/ inside the container.
    3. Image tag: The Docker image to deploy (e.g., unit:wasm).

    Use the -r flag to set the application directory mount as read-only (note: this breaks compatibility with apps like WordPress that require filesystem writes).

    After deployment, the new container will appear in the unitctl instances list.