NGINX Unit

Packaging Custom Modules§

There’s always a chance that you need to run a language version that isn’t yet available among the official Unit packages but still want to benefit from the convenience of a packaged installation. In this case, you can build your own package to be installed alongside the official distribution, adding the latter as a prerequisite.

Here, we are packaging a custom PHP 7.3 module to be installed next to the official Unit package; adjust the command samples to your scenario as needed. For Debian, Ubuntu, and other .deb-based distributions, see the steps here; for CentOS, Fedora, RHEL, and other .rpm-based distributions, follow the steps here.

Note

For elaborate Unit packaging examples, refer to our packaging system sources.

.deb Packages§

Assuming you are packaging for the current system and have the official Unit package installed:

  1. Make sure to install the prerequisites for the package. In our example, it’s PHP 7.3 on Debian 10:

    # apt update
    # apt install ca-certificates apt-transport-https
    # curl -sL https://packages.sury.org/php/apt.gpg | apt-key add -
    # echo "deb https://packages.sury.org/php/ buster main" \
           > /etc/apt/sources.list.d/php.list
    # apt update
    # apt install php7.3
    # apt install php-dev libphp-embed
    
  2. Create a staging directory for your package:

    $ export UNITTMP=$(mktemp -d -p /tmp -t unit.XXXXXX)
    $ mkdir -p $UNITTMP/unit-php7.3/DEBIAN
    $ cd $UNITTMP
    

    This creates a folder structure fit for dpkg-deb; the DEBIAN folder will store the package definition.

  3. Run unitd --version as root and note the ./configure flags for later use:

    # unitd --version
    
        unit version: 1.9.0
        configured as ./configure <./configure flags>
    
  4. Download Unit sources, configure and build your custom module, then put it where Unit will find it:

    $ curl -O https://unit.nginx.org/download/unit-1.9.0.tar.gz
    $ tar xzf unit-1.9.0.tar.gz                                  # Puts Unit sources in the unit-1.9.0 subdirectory
    $ cd unit-1.9.0
    $ ./configure <./configure flags>                            # Configures the build; use the ./configure flags from unitd output
    $ ./configure php --module=php7.3 --config=php-config        # Configures the module itself
    $ make php7.3                                                # Builds the module in the build/ subdirectory
    $ mkdir -p $UNITTMP/unit-php7.3/<module path>                # Use the module path from the ./configure flags
    $ mv build/php7.3.unit.so $UNITTMP/unit-php7.3/<module path> # Adds the module to the package
    
  5. Create a control file in the $UNITTMP/unit-php7.3/DEBIAN/ directory; list unit with other dependencies:

    Package: unit-php7.3
    Version: 1.9.0
    Comment0: Use Unit package version for consistency: 'apt show unit | grep Version'
    Architecture: amd64
    Comment1: To get current architecture, run 'dpkg --print-architecture'
    Comment2: For a list of other options, run 'dpkg-architecture -L'
    Depends: unit (= 1.9.0), php7.3, libphp-embed
    Comment3: Specify Unit package version to avoid issues when Unit updates
    Comment4: Again, run 'apt show unit | grep Version' to get this value
    Maintainer: Jane Doe <j.doe@example.com>
    Description: Custom PHP 7.3 language module for NGINX Unit 1.9.0
    

    Save and close the file.

  6. Build and install the package:

    $ dpkg-deb -b $UNITTMP/unit-php7.3
    # dpkg -i $UNITTMP/unit-7.3.deb
    
  7. Finally, restart Unit and check out the log to make sure your module was loaded:

    # systemctl restart unit
    # less /path/to/unit.log
    
        ...
       [info] discovery started
       [notice] module: <module name and version> "<module path>/php7.3.unit.so"
    

.rpm Packages§

Assuming you are packaging for the current system and have the official Unit package installed:

  1. Make sure to install the prerequisites for the package. In our example, it’s PHP 7.3 on Fedora 30:

    # yum install -y php-7.3.8
    # yum install php-devel php-embedded
    
  2. Install RPM development tools and prepare the directory structure:

    # yum install -y rpmdevtools
    $ rpmdev-setuptree
    
  3. Create a .spec file for your custom package:

    $ cd ~/rpmbuild/SPECS
    $ rpmdev-newspec unit-php7.3
    
  4. Run unitd --version as root and note the ./configure flags for later use:

    # unitd --version
    
        unit version: 1.9.0
        configured as ./configure <./configure flags>
    
  5. Edit the unit-php7.3.spec file as follows (see inline comments for details):

    Name:           unit-php7.3
    Version:        1.9.0
    # Use Unit package version for consistency: 'yum info unit | grep Version'
    Release:        1%{?dist}
    Summary:        Custom language module for NGINX Unit
    
    License:        ASL 2.0
    # Unit uses ASL 2.0; your license depends on the language you are packaging
    URL:            https://example.com
    BuildRequires:  gcc
    BuildRequires:  make
    BuildRequires:  php-devel
    BuildRequires:  php-embedded
    Requires:       unit = 1.9.0
    # Specify Unit package version to avoid issues when Unit updates
    # Again, run 'yum info unit | grep Version' to get this value
    Requires:       php >= 7.3
    Requires:       php-embedded
    
    %description
    Custom language module for NGINX Unit 1.9.0 (https://unit.nginx.org).
    
    Maintainer: Jane Doe <j.doe@example.com>
    
    %prep
    curl -O https://unit.nginx.org/download/unit-1.9.0.tar.gz
    # Downloads Unit sources
    tar --strip-components=1 -xzf unit-1.9.0.tar.gz
    # Extracts them locally for compilation steps in the %build section
    
    %build
    ./configure <./configure flags>
    # Configures the build; use the ./configure flags from unitd output
    ./configure php --module=php7.3 --config=php-config
    # Configures the module itself
    make php7.3
    # Builds the module
    
    %install
    DESTDIR=%{buildroot} make php7.3-install
    # Adds the module to the package
    
    %files
    %attr(0755, root, root) "<module path>/php7.3.unit.so"
    # Lists the module as package contents to include it in the package build
    # Use the module path from the ./configure flags
    

    Save and close the file.

  6. Build and install the package:

    $ rpmbuild -bb unit-php7.3.spec
    
        ...
        Wrote: /home/user/rpmbuild/RPMS/<arch>/unit-php7.3-<version>.<arch>.rpm
        ...
    
    # yum install -y /home/user/rpmbuild/RPMS/<arch>/unit-php7.3-<version>.<arch>.rpm
    
  7. Finally, restart Unit and check out the log to make sure your module was loaded:

    # systemctl restart unit
    # less /path/to/unit.log
    
        ...
       [info] discovery started
       [notice] module: <module name and version> "<module path>/php7.3.unit.so"