diff --git a/.gitignore b/.gitignore index 74672558..72724fc4 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,5 @@ output.txt rss.xml /.idea/ /CLAUDE.md +/QWEN.md +/.qwen \ No newline at end of file diff --git a/Dockerfile.local b/Dockerfile.local new file mode 100644 index 00000000..6d1850ef --- /dev/null +++ b/Dockerfile.local @@ -0,0 +1,14 @@ +FROM python:3.12-slim + +RUN apt-get update && apt-get install -y --no-install-recommends make rsync curl gnupg && rm -rf /var/lib/apt/lists/* + +WORKDIR /docs + +COPY requirements.txt . +RUN pip install -r requirements.txt + +COPY . . + +EXPOSE 8000 + +CMD ["make", "serve"] diff --git a/README.md b/README.md index 7262dda3..3beaf79f 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,14 @@ pip install -r requirements.txt make serve ``` +## Docker (local) +```shell +docker stop freeunit-docs; docker rm freeunit-docs 2>/dev/null; docker build -f Dockerfile.local -t freeunit-docs-local . && docker run -d -p 8000:8000 --name freeunit-docs freeunit-docs-local +http://localhost:8000/ +``` + + + The site is served locally at `http://localhost:8000`. Pull requests automatically deploy a preview site when opened by a maintainer. diff --git a/source/installation.rst b/source/installation.rst index c6a055bb..7d50bf15 100644 --- a/source/installation.rst +++ b/source/installation.rst @@ -9,22 +9,35 @@ Installation ############ +.. warning:: + **Official FreeUnit RPM/DEB packages are coming soon.** + As of April 2026, FreeUnit is distributed via Docker images, + source builds, and pre-built ``unitctl`` binaries from GitHub Releases. + The ``packages.nginx.org/unit/*`` repositories described below + belong to the archived NGINX Unit project and will not receive further + updates — use them only to migrate off. + See the :doc:`migration` guide for the current install paths + and for maintainer instructions on rebasing community packages. + You can install FreeUnit in four alternative ways: - Choose from our official :ref:`binary packages ` - for a few popular systems. - They're as easy to use as any other packaged software - and suit most purposes straight out of the box. + for a few popular systems (**coming soon** — see the + :doc:`migration guide ` for the current status + and :ref:`Docker ` / :ref:`Source ` + install paths). - If your preferred OS or language version is missing from the official package list, try :ref:`third-party repositories `. Be warned, though: we don't maintain them. + Packagers updating those recipes should follow the + :ref:`maintainer guide `. -- Run our :ref:`Docker official images `, +- Run our :ref:`Docker official images `, prepackaged with varied language combinations. -- To fine-tune Unit to your goals, +- To fine-tune FreeUnit to your goals, download the :ref:`sources `, install the :ref:`toolchain `, and :ref:`build ` a custom binary from scratch; @@ -90,9 +103,18 @@ Optional dependencies: Official packages ***************** -Installing an official precompiled Unit binary package -is best on most occasions; -they're available for: +.. warning:: + **Official FreeUnit RPM/DEB packages are coming soon.** + The repositories, keys, and package names documented in this section + (``packages.nginx.org/unit/*``, ``nginx-keyring.gpg``, ``unit``, + ``unit-php``, …) refer to the **archived NGINX Unit** project and + are kept here for reference only. Until FreeUnit's native packages + land, install via :ref:`Docker ` or a + :ref:`source build `. + Progress: https://github.com/freeunitorg/freeunit/milestone/2 + +Historically, official precompiled Unit binary packages +have been available for: - Amazon |_| Linux :ref:`AMI `, Amazon |_| Linux |_| :ref:`2 `, @@ -128,20 +150,17 @@ at the `npm `_ registry. .. nxt_details:: Repo installation script :hash: repo-install - We provide a `script `__ - that adds our official repos on the systems we support: + .. warning:: - .. code-block:: console + This script targets the archived NGINX Unit repositories + (``packages.nginx.org/unit/*``) and is **not** compatible with FreeUnit. + Use the manual steps below for each distribution, + or install via :ref:`Docker ` / + :ref:`source build `. - $ wget https://raw.githubusercontent.com/nginx/unit/master/tools/setup-unit && chmod +x setup-unit - - .. code-block:: console - - # ./setup-unit repo-config - - Use it at your discretion; - explicit steps are provided below - for each distribution. + The original script is archived at + `github.com/nginx/unit/tree/master/tools + `__ for reference only. .. _installation-precomp-amazon: @@ -920,13 +939,18 @@ macOS .. tab:: Homebrew - To install Unit on macOS, - use the official Homebrew - `tap `_: + .. warning:: + + The Homebrew tap for FreeUnit is not yet published. + Install via :ref:`Docker ` or a + :ref:`source build ` until the tap lands. + + Previously, Unit on macOS was installed via the + `nginx/homebrew-unit `_ tap: .. code-block:: console - $ brew install nginx/unit/unit + $ brew install nginx/unit/unit # archived; do not use This deploys the core Unit binary and the prerequisites for the @@ -1053,21 +1077,21 @@ If you update Unit later, make sure to update the module as well: $ npm install -g node-gyp - Next, clone the Unit source code to build a :program:`unit-http` module + Next, clone the FreeUnit source to build a :program:`unit-http` module for the selected Node.js version: .. code-block:: console - $ git clone https://github.com/nginx/unit + $ git clone https://github.com/freeunitorg/freeunit .. code-block:: console - $ cd unit + $ cd freeunit .. code-block:: console $ pwd - :nxt_hint:`/home/user/unit ` + :nxt_hint:`/home/user/freeunit ` .. code-block:: console @@ -1090,7 +1114,7 @@ If you update Unit later, make sure to update the module as well: .. code-block:: console - $ CPPFLAGS="-I/home/user/unit/include/" LDFLAGS="-L/home/user/unit/lib/" \ + $ CPPFLAGS="-I/home/user/freeunit/include/" LDFLAGS="-L/home/user/freeunit/lib/" \ make node-install .. code-block:: console @@ -1179,8 +1203,17 @@ Community Repositories .. warning:: These distributions are maintained by their respective communities, - not NGINX. - Use them with caution. + not the FreeUnit project. + Use them with caution — they still ship the archived ``unit``/ + ``nginx-unit`` packages and may lag several releases behind. + +.. note:: + **For package maintainers:** the steps to rebase these recipes onto + ``freeunitorg/freeunit`` (rename the package, swap the source URL, + add ``provides``/``obsoletes`` aliases, refresh checksums) are + documented in + :ref:`Community Repository Maintainers ` + in the migration guide. .. Legacy anchors are left here so that external links remain valid @@ -1913,217 +1946,80 @@ Community Repositories Docker Images ************* -Unit's Docker images -come in several language-specific flavors: +FreeUnit images are published to +`GitHub Container Registry `_ +as multi-arch manifests (``amd64`` + ``arm64``). + +Tag format: :samp:`{VERSION}-{VARIANT}` (pinned) or :samp:`latest-{VARIANT}` (rolling). .. list-table:: :header-rows: 1 + :widths: 30 70 - * - Tag + * - Variant - Description - * - :samp:`|version|-minimal` - - No language modules; - based on the **debian:bullseye-slim** - `image `__. - - * - :samp:`|version|-go1.21` - - Single-language; - based on the **golang:1.21** - `image `__. - - * - :samp:`|version|-jsc11` - - Single-language; - based on the **eclipse-temurin:11-jdk** - `image `__. - - * - :samp:`|version|-node20` - - Single-language; - based on the **node:20** - `image `__. - - * - :samp:`|version|-perl5.38` - - Single-language; - based on the **perl:5.38** - `image `__. - - * - :samp:`|version|-php8.2` - - Single-language; - based on the **php:8.2-cli** - `image `__. - - * - :samp:`|version|-python3.11` - - Single-language; - based on the **python:3.11** - `image `__. - - * - :samp:`|version|-ruby3.2` - - Single-language; - based on the **ruby:3.2** - `image `__. - - * - :samp:`|version|-wasm` - - Single-language; - based on the **debian:bullseye-slim** - `image `__. - -.. nxt_details:: Customizing language versions in Docker images - :hash: inst-lang-docker + * - ``minimal`` + - No language modules. Base for custom images. - To build a custom language version image, - clone and rebuild the sources locally - with Docker installed: + * - ``wasm`` + - WebAssembly Components (WASI 0.2) via Wasmtime. - .. code-block:: console + * - ``go1.24`` ``go1.25`` ``go1.26`` + - Go (single-version images). - $ make build- VERSIONS_= + * - ``jsc17`` ``jsc21`` + - Java Servlet Container via Eclipse Temurin OpenJDK LTS. + Runs ``.war``/``.jsp`` applications. - The :program:`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. + * - ``node20`` ``node22`` ``node24`` + - Node.js (single-version images). - .. note:: + * - ``perl5.38`` ``perl5.40`` + - Perl (single-version images). - Unit relies on the official Docker images, - so any customization method offered by their maintainers - is equally applicable; - to tailor a Unit image to your needs, - see the quick reference for its base image. + * - ``php8.3`` ``php8.4`` ``php8.5`` + - PHP (single-version images). - The language name can be - **go**, **jsc**, **node**, **perl**, - **php**, **python**, or **ruby**; - the version is defined as **.**, - except for **jsc** and **node** - that take only major version numbers - (as seen in the tag table). - Thus, to create an image with Python 3.10 - and tag it as **unit:|version|-python3.10**: + * - ``python3.12`` ``python3.12-slim`` + - Python 3.12, full and slim variants. - .. subs-code-block:: console + * - ``python3.13`` ``python3.13-slim`` + - Python 3.13, full and slim variants. - $ git clone https://github.com/nginx/unit + * - ``python3.14`` ``python3.14-slim`` + - Python 3.14, full and slim variants. - .. code-block:: console + * - ``ruby3.3`` ``ruby3.4`` + - Ruby (single-version images). - $ cd unit +To pull and run an image: - .. code-block:: console +.. code-block:: console - $ git checkout |version| # Optional; use to choose a specific Unit version + $ docker pull ghcr.io/freeunitorg/freeunit::nxt_ph:`TAG ` - .. code-block:: console +.. code-block:: console - $ cd pkg/docker/ + $ docker run -d ghcr.io/freeunitorg/freeunit::nxt_ph:`TAG ` + +.. nxt_details:: Building custom language-version images + :hash: inst-lang-docker + + Clone the FreeUnit source, then build a specific variant locally: .. code-block:: console - $ make build-:nxt_ph:`python3.10 ` VERSIONS_:nxt_ph:`python `=:nxt_ph:`3.10 ` + $ git clone https://github.com/freeunitorg/freeunit + $ cd freeunit + $ docker build -f pkg/docker/Dockerfile.:nxt_ph:`VARIANT ` pkg/docker/ - For details, see the - `Makefile - `__. + See ``pkg/docker/`` for all available Dockerfiles and the + `Makefile `__ + for the full build pipeline. For other customization scenarios, see the :doc:`Docker howto `. -.. nxt_details:: Images with pre-1.29.1 Unit versions - :hash: inst-pre-official-docker - - Before Unit 1.29.1 was released, - our Docker images were available - from the official - `NGINX repository `_ - on Docker Hub. - -.. nxt_details:: Images with pre-1.22.0 Unit versions - :hash: inst-legacy-docker - - Before Unit 1.22.0 was released, - the following tagging scheme was used: - - .. list-table:: - :header-rows: 1 - - * - Tag - - Description - - * - **-full** - - Contains modules for all languages that Unit then supported. - - * - **-minimal** - - No language modules were included. - - * - **-** - - 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: - -.. tabs:: - :prefix: docker - - .. tab:: Docker Hub - - To install and run Unit from - `official builds `__ - at Docker Hub: - - .. code-block:: console - - $ docker pull unit::nxt_ph:`TAG ` - - .. code-block:: console - - $ docker run -d unit::nxt_ph:`TAG ` - - - .. tab:: Amazon ECR Public Gallery - - To install and run Unit from NGINX's - `repository `__ - at Amazon ECR Public Gallery: - - .. code-block:: console - - $ docker pull public.ecr.aws/nginx/unit::nxt_ph:`TAG ` - - .. code-block:: console - - $ docker run -d public.ecr.aws/nginx/unit::nxt_ph:`TAG ` - - - .. tab:: packages.nginx.org - - .. warning:: - - Unit's 1.30+ image tarballs aren't published on the website; - this channel is deprecated. - - To install and run Unit - from the tarballs stored on our - `website `_: - - .. subs-code-block:: console - - $ curl -O https://packages.nginx.org/unit/docker/1.29.1/nginx-unit-:nxt_ph:`TAG `.tar.gz - - .. code-block:: console - - $ curl -O https://packages.nginx.org/unit/docker/1.29.1/nginx-unit-:nxt_ph:`TAG `.tar.gz.sha512 - - .. code-block:: console - - $ sha512sum -c nginx-unit-:nxt_ph:`TAG `.tar.gz.sha512 - nginx-unit-:nxt_ph:`TAG `.tar.gz: OK - - .. code-block:: console - - $ docker load < nginx-unit-:nxt_ph:`TAG `.tar.gz - Runtime details: .. list-table:: @@ -2139,12 +2035,9 @@ Runtime details: * - Non-privileged :ref:`user and group ` - **unit** -For more details, -see the repository pages -(`Docker Hub `_, -`Amazon ECR Public Gallery `_) -and our -:doc:`Docker howto `. +For full image details, see the +`GHCR package page `_ +and our :doc:`Docker howto `. .. _installation-docker-init: @@ -2200,7 +2093,7 @@ to your **Dockerfile** derived from an official image: .. subs-code-block:: docker - FROM unit:|version|-minimal + FROM ghcr.io/freeunitorg/freeunit:|version|-minimal COPY ./*.pem /docker-entrypoint.d/ COPY ./*.json /docker-entrypoint.d/ COPY ./*.sh /docker-entrypoint.d/ @@ -2223,7 +2116,7 @@ to a container at startup: $ docker run -d --mount \ type=bind,src=:nxt_ph:`/path/to/config/files/ `,dst=/docker-entrypoint.d/ \ - unit:|version|-minimal) + ghcr.io/freeunitorg/freeunit:|version|-minimal .. _source: @@ -2232,9 +2125,9 @@ to a container at startup: Source Code *********** -You can get Unit's source code -from our official GitHub repository -or as a tarball. +FreeUnit's source code lives in the community-maintained fork +at `github.com/freeunitorg/freeunit +`_. .. tabs:: :prefix: get-source @@ -2243,7 +2136,7 @@ or as a tarball. .. subs-code-block:: console - $ git clone https://github.com/nginx/unit # Latest updates to the repository + $ git clone https://github.com/freeunitorg/freeunit # Latest updates to the repository .. subs-code-block:: console @@ -2251,26 +2144,26 @@ or as a tarball. .. subs-code-block:: console - $ git clone -b |version| https://github.com/nginx/unit # Specific version tag; see https://github.com/nginx/unit/tags + $ git clone -b |version| https://github.com/freeunitorg/freeunit # Specific version tag; see https://github.com/freeunitorg/freeunit/tags .. subs-code-block:: console - $ cd unit + $ cd freeunit .. tab:: Tarball .. subs-code-block:: console - $ curl -O https://sources.nginx.org/unit/unit-|version|.tar.gz + $ curl -LO https://github.com/freeunitorg/freeunit/archive/refs/tags/|version|.tar.gz .. subs-code-block:: console - $ tar xzf unit-|version|.tar.gz + $ tar xzf |version|.tar.gz .. subs-code-block:: console - $ cd unit-|version| + $ cd freeunit-|version| To build Unit and specific language modules from these sources, refer to the diff --git a/source/migration.rst b/source/migration.rst new file mode 100644 index 00000000..76fb744e --- /dev/null +++ b/source/migration.rst @@ -0,0 +1,1142 @@ +.. meta:: + :og:description: Migrate from archived Unit installations or community packages + to the community-maintained FreeUnit fork, including maintainer guidance + for updating downstream packaging recipes. + +.. include:: include/replace.rst + +######### +Migration +######### + +This guide covers two audiences: + +- **Users** running archived Unit or a community-maintained package + who want to switch to **FreeUnit**, the community-maintained LTS fork. +- **Package maintainers** of community repositories (Alpine, Arch, Gentoo, + *BSD, Nix, Remi, etc.) who need to rebase their recipes onto the + ``freeunitorg/freeunit`` source tree. + +.. note:: + FreeUnit is ABI-compatible with previous Unit builds. + Functionally nothing changes — only the **package name** + (``unit``/``nginx-unit`` → ``freeunit``) and the **upstream source URL** + (``github.com/nginx/unit`` → ``github.com/freeunitorg/freeunit``). + ``config.json``, runtime paths, CLI flags, and the control API stay as-is. + +.. warning:: + **Official RPM/DEB packages for FreeUnit are coming soon.** + As of April 2026, FreeUnit is distributed via: + + - :ref:`Docker official images ` + - :ref:`Source builds ` + - Pre-built ``unitctl`` binaries from GitHub Releases + + Native package manager support (APT/YUM) is in active development. + Track progress at: https://github.com/freeunitorg/freeunit/milestone/2 + +**For users** — pick one install path: + +- Run our :ref:`Docker official images `, + prepackaged with varied language combinations. + +- To fine-tune FreeUnit to your goals, + download the :ref:`sources `, + install the :ref:`toolchain `, + and :ref:`build ` a custom binary from scratch. + +- For RHEL/Fedora users who want to keep Remi's PHP packages, + try the :ref:`hybrid approach ` + (FreeUnit core + Remi PHP modules). + +**For package maintainers** — rebase your recipe: + +- Follow + :ref:`Community Repository Maintainers ` + below for per-distro steps (source URL, rename, ``provides``/ + ``obsoletes`` aliases, checksums). + +.. note:: + The commands in this document starting with a hash (#) must be run as root or + with superuser privileges. + +.. _migration-community-repos: + +*********************************** +Community Repository Maintainers +*********************************** + +This section targets **downstream packagers** who maintain a Unit recipe +in a community repository (AUR, Alpine aports, Gentoo ::gentoo, +FreeBSD ports, Remi's RPM, etc.) and want to track FreeUnit going forward. + +The rebase is mechanical: + +#. Change the **source URL** from + ``https://github.com/nginx/unit`` to + ``https://github.com/freeunitorg/freeunit``. +#. Rename the **package** from ``unit`` (or ``nginx-unit``) to ``freeunit``. + Rename subpackages accordingly + (``unit-php`` → ``freeunit-php``, ``unit-python3`` → ``freeunit-python3``, …). +#. Keep the old name as a ``provides``/``replaces``/``obsoletes`` alias + so existing installs upgrade cleanly. +#. Update signing/checksum metadata against the new release tarballs. +#. Verify runtime paths still match the table at the end of each tab — + upstream does not enforce a layout, so distro defaults are preserved. + +.. note:: + FreeUnit release tags follow the same ``1.X.Y`` scheme as archived Unit, + starting from the last Unit release. Tarballs: + ``https://github.com/freeunitorg/freeunit/archive/refs/tags/.tar.gz``. + +.. warning:: + These distributions are maintained by their respective communities, + not the FreeUnit project. + Packages may be outdated or lack security updates. + +.. tabs:: + :prefix: community + :toc: + + .. tab:: Alpine + + Recipe: ``community/unit/APKBUILD`` in + `alpinelinux/aports `_. + + #. **Rename the aport** + + Move ``community/unit/`` to ``community/freeunit/`` and update + ``APKBUILD``: + + .. code-block:: sh + :caption: community/freeunit/APKBUILD + + pkgname=freeunit + pkgver=1.35.3 + source="$pkgname-$pkgver.tar.gz::https://github.com/freeunitorg/freeunit/archive/refs/tags/$pkgver.tar.gz" + builddir="$srcdir/freeunit-$pkgver" + subpackages="$pkgname-openrc $pkgname-doc $pkgname-dev + $pkgname-perl $pkgname-php83 $pkgname-python3 $pkgname-ruby" + provides="unit=$pkgver-r$pkgrel" + replaces="unit" + + #. **Refresh checksums** + + .. code-block:: console + + $ abuild checksum + + #. **Build and test** + + .. code-block:: console + + $ abuild -r + + #. **Submit an MR** to aports following the + `Alpine contributing guide + `_. + + Runtime details (unchanged from the legacy ``unit`` aport): + + .. list-table:: + + * - Control :ref:`socket` + - **/run/control.unit.sock** + + * - Log :ref:`file` + - **/var/log/unit.log** + + * - Non-privileged :ref:`user and group` + - **unit** + + .. tab:: ALT + + Recipe: ``unit.spec`` in the Sisyphus + `gears/u/unit + `_ repository. + + #. **Clone the gear and branch it** + + .. code-block:: console + + $ git clone git://git.altlinux.org/gears/u/unit.git freeunit + $ cd freeunit + + #. **Update the spec** + + .. code-block:: spec + :caption: freeunit.spec + + Name: freeunit + Version: 1.35.3 + Source0: https://github.com/freeunitorg/freeunit/archive/refs/tags/%version.tar.gz + Provides: unit = %EVR + Obsoletes: unit < %EVR + + Rename subpackages the same way + (``unit-perl`` → ``freeunit-perl``, ``unit-php`` → ``freeunit-php``, …). + + #. **Rebuild in the hasher** + + .. code-block:: console + + $ gear-rpm -bb + $ hsh --init && hsh --build freeunit-*.src.rpm + + #. **Push to Sisyphus** via + ``gear-commit`` + ``git push`` once a maintainer has reviewed. + + Runtime details (unchanged from the legacy ``unit`` gear): + + .. list-table:: + + * - Control :ref:`socket` + - **/run/unit/control.sock** + + * - Log :ref:`file` + - **/var/log/unit/unit.log** + + * - Non-privileged :ref:`user and group` + - **_unit** (mind the **_** prefix) + + .. tab:: Arch + + Recipe: ``PKGBUILD`` in the + `nginx-unit AUR package + `_. + + Recommended path: publish a **new AUR package named** ``freeunit`` and + keep ``nginx-unit`` around for a release or two pointing at the same + tarball (``provides=('nginx-unit')``, ``conflicts=('nginx-unit')``). + + #. **Clone the AUR repo and rename** + + .. code-block:: console + + $ git clone ssh://aur@aur.archlinux.org/freeunit.git + $ cd freeunit + + #. **Update PKGBUILD** + + .. code-block:: sh + :caption: PKGBUILD + + pkgbase=freeunit + pkgname=('freeunit' 'freeunit-php' 'freeunit-python' 'freeunit-nodejs') + pkgver=1.35.3 + url='https://github.com/freeunitorg/freeunit' + source=("freeunit-$pkgver.tar.gz::https://github.com/freeunitorg/freeunit/archive/refs/tags/$pkgver.tar.gz") + provides=("nginx-unit=$pkgver") + replaces=('nginx-unit') + conflicts=('nginx-unit') + + #. **Refresh checksums and .SRCINFO** + + .. code-block:: console + + $ updpkgsums + $ makepkg --printsrcinfo > .SRCINFO + + #. **Build in a clean chroot, then push** + + .. code-block:: console + + $ makepkg -s + $ git commit -am "freeunit 1.35.3: rebase on freeunitorg/freeunit" + $ git push + + .. warning:: + AUR packages are user-produced without pre-moderation. + Audit the ``PKGBUILD`` and any ``.install`` scripts before publishing. + + Runtime details (unchanged from the legacy ``nginx-unit`` AUR package): + + .. list-table:: + + * - Control :ref:`socket` + - **/run/unit/control.sock** + + * - Log :ref:`file` + - **/var/log/unit/unit.log** + + * - Non-privileged :ref:`user and group` + - **nobody** + + .. tab:: FreeBSD + + Recipe: the ``www/unit`` port in + `freebsd/freebsd-ports + `_. + + Strategy: create a new slave-free port ``www/freeunit`` and mark the + old ``www/unit`` port deprecated with ``MOVED`` redirect. + + #. **Copy the port tree** + + .. code-block:: console + + $ cp -R www/unit www/freeunit + $ cp -R www/unit-php www/freeunit-php + $ cp -R www/unit-python www/freeunit-python + # …repeat for perl, ruby, wasm, libunit → libfreeunit + + #. **Update each Makefile** + + .. code-block:: make + :caption: www/freeunit/Makefile + + PORTNAME= freeunit + DISTVERSION= 1.35.3 + CATEGORIES= www + MAINTAINER= you@example.org + COMMENT= Dynamic application server, community LTS fork of NGINX Unit + + USE_GITHUB= yes + GH_ACCOUNT= freeunitorg + GH_PROJECT= freeunit + + CONFLICTS_INSTALL= unit-[0-9]* unit-php-[0-9]* unit-python-[0-9]* unit-perl-[0-9]* unit-ruby-[0-9]* unit-wasm-[0-9]* + + #. **Regenerate distinfo** + + .. code-block:: console + + $ make makesum + + #. **Register the rename in ``MOVED``** + + .. code-block:: text + + www/unit|www/freeunit|2026-04-19|Project renamed to FreeUnit + + #. **Test-build via poudriere, then submit a PR** to + `freebsd-ports `_. + + Runtime details (unchanged from the legacy ``www/unit`` port): + + .. list-table:: + + * - Control :ref:`socket` + - **/var/run/unit/control.unit.sock** + + * - Log :ref:`file` + - **/var/log/unit/unit.log** + + * - Non-privileged :ref:`user and group` + - **www** + + .. tab:: Gentoo + + Recipe: ``www-servers/nginx-unit`` in the + `::gentoo tree `_. + + Strategy: add ``www-servers/freeunit`` and last-rite ``nginx-unit`` by + adding a dated block to ``profiles/package.mask`` (with a 30-day removal + notice) once the replacement is stable. + + #. **Create the new package directory** + + .. code-block:: console + + $ git mv www-servers/nginx-unit www-servers/freeunit + $ cd www-servers/freeunit + $ git mv nginx-unit-1.34.2.ebuild freeunit-1.35.3.ebuild + + #. **Update the ebuild** + + .. code-block:: bash + :caption: www-servers/freeunit/freeunit-1.35.3.ebuild + + EAPI=8 + DESCRIPTION="Dynamic application server, community LTS fork of NGINX Unit" + HOMEPAGE="https://freeunit.org/" + SRC_URI="https://github.com/freeunitorg/freeunit/archive/refs/tags/${PV}.tar.gz -> ${P}.tar.gz" + S="${WORKDIR}/freeunit-${PV}" + + RDEPEND="!!`_ + per the `Gentoo developer manual + `_. + + Runtime details (unchanged from the legacy ``nginx-unit`` ebuild): + + .. list-table:: + + * - Control :ref:`socket` + - **/run/unit.sock** + + * - Log :ref:`file` + - **/var/log/unit.log** + + * - Non-privileged :ref:`user and group` + - **nobody** + + .. tab:: NetBSD + + Recipe: ``www/unit`` in + `pkgsrc `_. + + #. **Copy the category directory** + + .. code-block:: console + + $ cd pkgsrc/www + $ cp -R unit freeunit + + #. **Update the Makefile** + + .. code-block:: make + :caption: www/freeunit/Makefile + + DISTNAME= freeunit-1.35.3 + CATEGORIES= www + MASTER_SITES= ${MASTER_SITE_GITHUB:=freeunitorg/freeunit/} + GITHUB_TAG= ${PKGVERSION_NOREV} + HOMEPAGE= https://freeunit.org/ + COMMENT= Community LTS fork of NGINX Unit + + CONFLICTS+= unit-[0-9]* + SUPERSEDES+= unit-[0-9]* + + Do the same for ``www/freeunit-perl``, ``www/freeunit-python*``, + ``www/freeunit-ruby*``, ``devel/libfreeunit``. + + #. **Regenerate distinfo** + + .. code-block:: console + + $ make distinfo + + #. **Test-build** + + .. code-block:: console + + $ cd www/freeunit && make package + + #. **Commit and send-pr** via + `pkgsrc-wip `_ first if the rename needs + broader review. + + Runtime details (unchanged from the legacy ``www/unit`` pkgsrc entry): + + .. list-table:: + + * - Control :ref:`socket` + - **/var/run/unit/control.unit.sock** + + * - Log :ref:`file` + - **/var/log/unit/unit.log** + + * - Non-privileged :ref:`user and group` + - **unit** + + .. tab:: Nix + + Recipe: ``pkgs/servers/http/unit/default.nix`` in + `NixOS/nixpkgs `_. + + The NixOS module also lives at + ``nixos/modules/services/web-servers/unit/default.nix`` — + keep option names as aliases so existing configurations don't break. + + #. **Rename the derivation directory** + + .. code-block:: console + + $ git mv pkgs/servers/http/unit pkgs/servers/http/freeunit + + #. **Update default.nix** + + .. code-block:: nix + :caption: pkgs/servers/http/freeunit/default.nix + + stdenv.mkDerivation (finalAttrs: { + pname = "freeunit"; + version = "1.35.3"; + + src = fetchFromGitHub { + owner = "freeunitorg"; + repo = "freeunit"; + rev = finalAttrs.version; + hash = "sha256-..."; + }; + + meta = with lib; { + description = "Community LTS fork of NGINX Unit"; + homepage = "https://freeunit.org/"; + license = licenses.asl20; + }; + }) + + #. **Add an alias in ``pkgs/top-level/aliases.nix``** + + .. code-block:: nix + + unit = freeunit; # renamed 2026-04, remove after 25.11 + + #. **Update the NixOS module** to reference ``pkgs.freeunit`` and + add a ``mkRenamedOptionModule`` entry for ``services.unit.*`` → + ``services.freeunit.*``. + + #. **Refresh the hash and build** + + .. code-block:: console + + $ nix-prefetch-github --rev 1.35.3 freeunitorg freeunit # writes SRI hash for fetchFromGitHub (unpacked) + $ nix-build -A freeunit + $ nixos-rebuild build-vm -I nixpkgs=. + + #. **Submit a PR** to nixpkgs. + + Runtime details (unchanged from the legacy ``unit`` derivation): + + .. list-table:: + + * - Control :ref:`socket` + - **/run/unit/control.unit.sock** + + * - Log :ref:`file` + - **/var/log/unit/unit.log** + + * - Non-privileged :ref:`user and group` + - **unit** + + .. tab:: OpenBSD + + Recipe: ``www/unit`` in the + `OpenBSD ports tree + `_. + + #. **Create the new port** + + .. code-block:: console + + $ cd /usr/ports/www + $ cp -R unit freeunit + + #. **Update the Makefile** + + .. code-block:: make + :caption: www/freeunit/Makefile + + COMMENT = community LTS fork of NGINX Unit + GH_ACCOUNT = freeunitorg + GH_PROJECT = freeunit + GH_TAGNAME = 1.35.3 + DISTNAME = freeunit-${GH_TAGNAME} + PKGNAME = freeunit-${GH_TAGNAME} + + PSEUDO_FLAVORS = no_nonfree + FLAVORS = php python ruby perl + + Subpackage ``PKGNAME``s follow: ``freeunit-php``, ``freeunit-python``, + ``freeunit-perl``, ``freeunit-ruby``. + + #. **Regenerate distinfo** + + .. code-block:: console + + $ cd /usr/ports/www/freeunit && make makesum + + #. **Record the rename for ``pkg_add -u``** + + OpenBSD has no ports-wide ``MOVED`` file. Instead, add the old + pkgstem as an ``@pkgpath`` line in the new port's ``pkg/PLIST`` + so :program:`pkg_add -u` auto-upgrades ``unit-*`` installs: + + .. code-block:: text + :caption: www/freeunit/pkg/PLIST + + @pkgpath www/unit + @pkgpath www/unit,-main + + #. **Test-build and submit the diff** to + `ports@openbsd.org `_ + per the `OpenBSD porter's handbook + `_. + + Runtime details (unchanged from the legacy ``www/unit`` port): + + .. list-table:: + + * - Control :ref:`socket` + - **/var/run/unit/control.unit.sock** + + * - Log :ref:`file` + - **/var/log/unit/unit.log** + + * - Non-privileged :ref:`user and group` + - **_unit** + + .. tab:: Remi's RPM + + Recipe: Remi Collet builds from his own infrastructure — see + `blog.remirepo.net `_ for the canonical + spec tree and contact path. Coordinate the rename with Remi directly + rather than opening a PR to the GitHub mirror. + + The core package gets renamed; the PHP modules (``phpXX-unit-php``) + stay as-is — they are ABI-compatible with FreeUnit and Remi's naming + scheme is valuable to existing users. + + #. **Fork the spec to ``freeunit.spec``** + + .. code-block:: spec + :caption: freeunit.spec + + %global gh_owner freeunitorg + %global gh_project freeunit + + Name: freeunit + Version: 1.35.3 + Release: 1%{?dist} + Summary: Community LTS fork of NGINX Unit + URL: https://freeunit.org/ + Source0: https://github.com/%{gh_owner}/%{gh_project}/archive/refs/tags/%{version}.tar.gz + + Provides: unit = %{version}-%{release} + Obsoletes: unit < %{version}-%{release} + + %prep + %autosetup -n %{gh_project}-%{version} + + Leave ``--prefix=/usr`` in ``%configure`` so paths stay at + ``/usr/sbin/unitd`` and ``/usr/lib64/unit/modules/`` for drop-in + compatibility with ``phpXX-unit-php``. + + #. **Update ``phpXX-unit-php`` sub-specs** + + No rename required — only bump their + ``BuildRequires: freeunit-devel >= %{version}`` / + ``Requires: freeunit >= %{version}`` lines so they link against + the renamed core. + + #. **Build and hand the SRPM to Remi** + + .. code-block:: console + + $ rpmbuild -ba freeunit.spec + + The upload path into ``rpms.remirepo.net`` is Remi-internal — + don't invent one. Send the resulting SRPM to Remi via the contact + on `blog.remirepo.net `_ for repo + ingestion. + + #. **Verify the upgrade path** + + .. code-block:: console + + # dnf upgrade freeunit + # /usr/sbin/unitd --version + freeunit/1.35.3 + + Runtime details (unchanged from the legacy ``unit`` RPM): + + .. list-table:: + + * - Control :ref:`socket` + - **/run/unit/control.sock** + + * - Log :ref:`file` + - **/var/log/unit/unit.log** + + * - Non-privileged :ref:`user and group` + - **nobody** + +.. _migration-docker: + +**************** +Docker Migration +**************** + +FreeUnit provides official Docker images for easy deployment. + +.. _migration-docker-steps: + +==== +Steps +==== + +#. **Pick a tag and reference it** + + Images are hosted on GitHub Container Registry (GHCR): + https://github.com/freeunitorg/freeunit/pkgs/container/freeunit + + Tag format: :samp:`{VERSION}-{VARIANT}` (pinned) or + :samp:`latest-{VARIANT}` (rolling). There is **no bare** ``latest`` tag. + + .. list-table:: + :header-rows: 1 + :widths: 35 65 + + * - Variant + - Description + + * - ``minimal`` + - No language modules. Base for custom images. + + * - ``wasm`` + - WebAssembly Components (WASI 0.2) via Wasmtime. + + * - ``go1.24`` ``go1.25`` ``go1.26`` + - Go (single-version images). + + * - ``jsc17`` ``jsc21`` + - Java (Eclipse Temurin OpenJDK LTS). Runs ``.war``/``.jsp`` apps. + + * - ``node20`` ``node22`` ``node24`` + - Node.js (single-version images). + + * - ``perl5.38`` ``perl5.40`` + - Perl (single-version images). + + * - ``php8.3`` ``php8.4`` ``php8.5`` + - PHP (single-version images). + + * - ``python3.12`` ``python3.12-slim`` + - Python 3.12, full and slim. + + * - ``python3.13`` ``python3.13-slim`` + - Python 3.13, full and slim. + + * - ``python3.14`` ``python3.14-slim`` + - Python 3.14, full and slim. + + * - ``ruby3.3`` ``ruby3.4`` + - Ruby (single-version images). + + Each tag is available for both ``amd64`` and ``arm64`` architectures + via a multi-arch manifest. + + .. note:: + **Language version support policy:** FreeUnit supports each language + variant for **1 year after the upstream language EOL**. + When a variant is retired, it is removed from the matrix and noted + in ``CHANGES.txt``. EOL dates: https://endoflife.date + + Reference the image in your ``Dockerfile`` or ``docker-compose.yml``: + + .. code-block:: docker + :caption: Example — pinning PHP 8.4 + + FROM ghcr.io/freeunitorg/freeunit:1.35.3-php8.4 + + .. code-block:: docker + :caption: Example — rolling latest Python 3.13 + + FROM ghcr.io/freeunitorg/freeunit:latest-python3.13 + +#. **Verify the image** + + .. code-block:: console + + $ docker run --rm ghcr.io/freeunitorg/freeunit:latest-minimal unitd --version + freeunit/X.Y.Z # Example format; actual version may differ + + .. note:: + The ``freeunit/`` prefix confirms the community fork. + +#. **Deploy** + + Pull the image and start your containers: + + .. code-block:: console + + # docker-compose pull + # docker-compose up -d + +.. _migration-docker-custom: + +==== +Custom Images +==== + +If you build custom images, use FreeUnit as your base: + +.. code-block:: docker + :caption: Dockerfile + + FROM ghcr.io/freeunitorg/freeunit:minimal AS unit-base + + # Your custom layers below + COPY --from=unit-base /usr/lib/unit/modules /usr/lib/unit/modules + # ... rest of your Dockerfile + +.. note:: + All runtime paths, environment variables, and entrypoint behavior + remain unchanged. Your existing Docker configuration works as-is. + +.. _migration-source: + +**************** +Build FreeUnit from Source +**************** + +For bare-metal deployments or when you need maximum control, +build FreeUnit from source. + +.. _migration-source-prereqs: + +==== +Prerequisites +==== + +FreeUnit 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 + +App languages and platforms that FreeUnit can run: + +- Go || 1.24 or later +- Java || 17 or later (via JSC) +- Node.js || 20 or later +- PHP || 8.3, 8.4, 8.5 +- Perl || 5.38 or later +- Python || 3.12, 3.13, 3.14 +- Ruby || 3.3 or later +- WebAssembly Components WASI || 0.2 + +Optional dependencies: + +- OpenSSL 1.0.1 or later for :ref:`TLS` support +- PCRE (8.0+) or PCRE2 (10.23+) for :ref:`regex` +- Wasmtime for WebAssembly support + +.. _migration-source-build: + +==== +Build and Install FreeUnit +==== + +#. **Clone the FreeUnit repository** + + .. code-block:: console + + $ git clone https://github.com/freeunitorg/freeunit + $ cd freeunit + +#. **Configure the FreeUnit build** + + Enable the modules you need: + + .. code-block:: console + + $ ./configure --openssl --otel \ + --modules=php:8.4,python:3.13,nodejs:22,go1.25,ruby3.4,perl5.40 + + .. note:: + Run ``./configure --help`` to see all available options. + For PHP, you can specify multiple versions: ``php:8.3,php:8.4,php:8.5``. + Supported language versions as of April 2026: + + - **PHP**: 8.3, 8.4, 8.5 + - **Python**: 3.12, 3.13, 3.14 + - **Node.js**: 20, 22, 24 + - **Go**: 1.24, 1.25, 1.26 + - **Ruby**: 3.3, 3.4 + - **Perl**: 5.38, 5.40 + - **Java (JSC)**: 17, 21 (OpenJDK LTS for .war/.jsp applications) + - **WebAssembly**: WASI 0.2 + +#. **Compile and install FreeUnit** + + .. code-block:: console + + $ make + # make install # or: sudo make install + + This installs: + - ``unitd`` to ``/usr/local/sbin/`` + - ``unitctl`` to ``/usr/local/bin/`` + - Modules to ``/usr/local/lib/unit/modules/`` + - Default config directory: ``/usr/local/etc/unit/`` + +#. **Set up systemd service** (optional but recommended) + + Copy the provided unit file: + + .. code-block:: console + + # cp pkg/systemd/unit.service /etc/systemd/system/ + # systemctl daemon-reload + # systemctl enable --now unit + +#. **Verify the FreeUnit installation** + + .. code-block:: console + + $ unitd --version + freeunit/X.Y.Z + +.. _migration-runtime-compatibility: + +********************* +Runtime Compatibility +********************* + +FreeUnit preserves full compatibility with previous Unit builds: + +.. list-table:: + + * - Control socket + - ``/run/unit/control.sock`` (unchanged) + * - Log file + - ``/var/log/unit/unit.log`` (unchanged) + * - Configuration path + - ``/etc/unit/config.json`` (unchanged) + * - State directory + - ``/var/lib/unit/`` (unchanged) + * - User/group defaults + - ``unit:unit`` or distribution default (unchanged) + * - Systemd service name + - ``unit.service`` (unchanged) + +.. _migration-troubleshooting: + +**************** +Troubleshooting FreeUnit +**************** + +.. nxt_details:: FreeUnit fails to start after migration + :hash: migration-start-fail + + If FreeUnit doesn't start after updating: + + #. Check the log: + + .. code-block:: console + + # journalctl -u unit -n 50 + # tail -f /var/log/unit/unit.log + + #. Verify module compatibility: + + .. code-block:: console + + # ls -la /usr/lib64/unit/modules/ # RHEL/Fedora + # ls -la /usr/lib/unit/modules/ # Debian/Ubuntu + + #. Ensure matching versions: + + .. code-block:: console + + $ unitd --version + $ rpm -qa | grep unit # or: dpkg -l | grep unit + + All ``unit-*`` components should share the same version. + + #. Restart with debug output: + + .. code-block:: console + + # systemctl stop unit + # unitd --no-daemon --control /run/unit/control.sock --log /var/log/unit/unit.log + +.. nxt_details:: PHP module not detected in FreeUnit + :hash: migration-php-module + + If your PHP application isn't recognized by FreeUnit: + + #. Confirm the module is installed or built: + + .. code-block:: console + + # rpm -qa | grep unit-php # RHEL/Fedora (Remi packages) + # ./configure --help | grep php # Source build check + + #. Check module loading: + + .. code-block:: console + + # unitd --test-config /etc/unit/config.json + + #. Restart FreeUnit to reload modules: + + .. code-block:: console + + # systemctl restart unit + + #. Verify PHP SAPI in your app config: + + .. code-block:: json + :caption: Example application config + + { + "type": "php", + "root": "/var/www/myapp", + "index": "index.php", + "script": "index.php" + } + +.. _migration-roll-back: + +**************** +Rollback Procedure +**************** + +If you need to revert to the previous setup: + +#. **Stop FreeUnit** + + .. code-block:: console + + # systemctl stop unit + +#. **Restore previous binary or image** + + .. tabs:: + :prefix: rollback-method + + .. tab:: Docker + + Revert the image tag in your ``docker-compose.yml`` or ``Dockerfile``: + + .. code-block:: docker + + FROM ghcr.io/freeunitorg/freeunit:1.35.0-php8.4 # Previous pinned version; replace variant to match your image + + Then redeploy: + + .. code-block:: console + + # docker-compose pull + # docker-compose up -d + + .. tab:: Source build + + Rebuild the previous version from source: + + .. code-block:: console + + $ git clone https://github.com/freeunitorg/freeunit + $ cd freeunit + $ git checkout 1.35.0 # Or your previous version tag + $ ./configure --openssl + $ make + # make install + + .. tab:: Community repositories + + Reinstall the original package from your distribution: + + .. tabs:: + :prefix: rollback-reinstall + + .. tab:: Alpine + + .. code-block:: console + + # apk add unit + + .. tab:: Arch + + .. code-block:: console + + $ yay -S unit + + .. tab:: FreeBSD + + .. code-block:: console + + # pkg install unit + + .. tab:: Gentoo + + .. code-block:: console + + # emerge www-servers/unit + + .. tab:: Remi's RPM + + .. code-block:: console + + # dnf downgrade unit + # or: dnf install unit-1.35.0-1.remi + +#. **Restart** + + .. code-block:: console + + # systemctl start unit + +.. note:: + Configuration files in ``/etc/unit/`` and application data + in ``/var/lib/unit/`` are preserved during binary changes. + +.. _migration-faq: + +*** +FAQ +*** + +**Q: Will my config.json break after migrating to FreeUnit?** + +No. FreeUnit maintains 100% compatibility with previous Unit builds. +Your ``config.json`` works as-is. + +**Q: Can I mix FreeUnit core with Remi's PHP modules?** + +Yes. FreeUnit's core binary is ABI-compatible with Remi's +``phpXX-unit-php`` modules. This is the basis of the +:ref:`hybrid approach `. + +**Q: How do I verify I'm running FreeUnit?** + +Check the version string: + +.. code-block:: console + + $ unitd --version + freeunit/X.Y.Z # Example format; actual version may differ + +The ``freeunit/`` prefix confirms the community fork. + +**Q: What if I need PHP 8.2 or older?** + +FreeUnit provides modules for PHP 8.3, 8.4, and 8.5. +For older PHP versions, consider: + +- Using Remi's modules with FreeUnit core (compatible) +- Building legacy modules from source with custom ``./configure`` flags +- Containerizing legacy apps with Docker using pinned base images + +**Q: Is there a migration script for FreeUnit?** + +A helper script is planned for a future release. +Track progress on our roadmap: +https://github.com/freeunitorg/freeunit/milestone/3 + +Until then, follow the manual steps above — they take <5 minutes. + +**Q: Where is the GPG key for FreeUnit package verification?** + +Official RPM/DEB packages for FreeUnit are not yet available. +When they are released, the public key will be published at: +http://freeunit.org/media/keys/6C68B7AA.asc + +For source builds, verify commits via GitHub signatures: +https://github.com/freeunitorg/freeunit/commits/main + +.. seealso:: + + - :doc:`installation` — Install FreeUnit from scratch + - :doc:`configuration` — Application configuration reference + - :ref:`community` — Get help from the FreeUnit community \ No newline at end of file