From c513e830018f38541be2348d9804f5d9eea20c58 Mon Sep 17 00:00:00 2001 From: Alexandr Smirnov Date: Sat, 18 Apr 2026 23:05:40 +0300 Subject: [PATCH 1/3] docs: add migration guide - New migration.rst with Docker, source build, and community repo instructions - Compatible with FreeUnit v1.35.3+ - Follows installation.rst style guide --- source/migration.rst | 954 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 954 insertions(+) create mode 100644 source/migration.rst diff --git a/source/migration.rst b/source/migration.rst new file mode 100644 index 00000000..30482498 --- /dev/null +++ b/source/migration.rst @@ -0,0 +1,954 @@ +.. meta:: + :og:description: Migrate from archived Unit installations or community packages + to the community-maintained FreeUnit fork. + +.. include:: include/replace.rst + +######### +Migration +######### + +This guide helps you migrate from archived Unit installations +or community-maintained packages to **FreeUnit**, +the community-maintained LTS fork. + +.. note:: + FreeUnit is ABI-compatible with previous Unit builds. + In most cases, migration requires only switching to a new build source + — no configuration changes needed. + +.. 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 + +You can migrate to FreeUnit in three alternative ways: + +- 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). + +.. note:: + The commands in this document starting with a hash (#) must be run as root or + with superuser privileges. + +.. _migration-community-repos: + +****************************** +Community Repositories +****************************** + +.. 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 + + .. warning:: + Alpine's Unit packages may be outdated. + For security updates and PHP 8.3+ support, + migrating to the latest FreeUnit build is recommended. + + To migrate from Alpine's Unit packages to FreeUnit: + + #. **Remove existing Unit packages** + + .. code-block:: console + + # apk del unit unit-openrc unit-perl unit-php* unit-python* unit-ruby + + #. **Build FreeUnit from source** + + .. code-block:: console + + # apk add build-base openssl-dev pcre2-dev libxslt-dev + # git clone https://github.com/freeunitorg/freeunit + # cd freeunit + # ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 + # make + # make install + + #. **Set up OpenRC service** + + .. code-block:: console + + # cp pkg/openrc/unit /etc/init.d/ + # rc-update add unit + # rc-service unit restart + + Runtime details: + + .. 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 + + .. warning:: + ALT Linux's Unit packages may be outdated. + For security updates and PHP 8.3+ support, + migrating to the latest FreeUnit build is recommended. + + To migrate from ALT's Unit packages to FreeUnit: + + #. **Remove existing Unit packages** + + .. code-block:: console + + # apt-get remove unit unit-perl unit-php unit-python3 unit-ruby + + #. **Build FreeUnit from source** + + .. code-block:: console + + # apt-get install build-essential libssl-dev libpcre2-dev libxslt1-dev + # git clone https://github.com/freeunitorg/freeunit + # cd freeunit + # ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 + # make + # make install + + #. **Set up systemd service** + + .. code-block:: console + + # cp pkg/systemd/unit.service /etc/systemd/system/ + # systemctl daemon-reload + # systemctl enable --now unit + + Runtime details: + + .. 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 + + .. warning:: + Arch AUR Unit packages may be outdated. + For security updates and PHP 8.3+ support, + migrating to the latest FreeUnit build is recommended. + + To migrate from Arch's Unit packages to FreeUnit: + + #. **Remove existing AUR package** + + .. code-block:: console + + # pacman -R unit + + #. **Build FreeUnit from source** + + .. code-block:: console + + # pacman -S base-devel openssl pcre2 libxslt + # git clone https://github.com/freeunitorg/freeunit + # cd freeunit + # ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 + # make + # make install + + #. **Set up systemd service** + + .. code-block:: console + + # cp pkg/systemd/unit.service /etc/systemd/system/ + # systemctl daemon-reload + # systemctl enable --now unit + + Runtime details: + + .. 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 + + .. warning:: + FreeBSD ports/packages for Unit may be outdated. + For security updates and PHP 8.3+ support, + migrating to the latest FreeUnit build is recommended. + + To migrate from FreeBSD's Unit packages to FreeUnit: + + #. **Remove existing packages** + + .. code-block:: console + + # pkg remove unit libunit unit-php* unit-python* unit-ruby* + + #. **Build FreeUnit from source** + + .. code-block:: console + + # pkg install git openssl pcre2 libxslt + # git clone https://github.com/freeunitorg/freeunit + # cd freeunit + # ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 + # make + # make install + + #. **Set up service** + + .. code-block:: console + + # cp pkg/freebsd/unitd /usr/local/etc/rc.d/ + # sysrc unitd_enable=YES + # service unitd restart + + Runtime details: + + .. 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 + + .. warning:: + Gentoo ebuilds for Unit may be outdated. + For security updates and PHP 8.3+ support, + migrating to the latest FreeUnit build is recommended. + + To migrate from Gentoo's Unit packages to FreeUnit: + + #. **Remove existing package** + + .. code-block:: console + + # emerge --deselect www-servers/unit + # emerge --depclean + + #. **Build FreeUnit from source** + + .. code-block:: console + + # emerge dev-vcs/git dev-libs/openssl dev-libs/libpcre2 dev-libs/libxslt + # git clone https://github.com/freeunitorg/freeunit + # cd freeunit + # ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 + # make + # make install + + #. **Set up OpenRC service** + + .. code-block:: console + + # cp pkg/openrc/unit /etc/init.d/ + # rc-update add unit + # rc-service unit restart + + Runtime details: + + .. list-table:: + + * - Control :ref:`socket` + - **/run/unit.sock** + + * - Log :ref:`file` + - **/var/log/unit.log** + + * - Non-privileged :ref:`user and group` + - **nobody** + + .. tab:: NetBSD + + .. warning:: + NetBSD packages for Unit may be outdated. + For security updates and PHP 8.3+ support, + migrating to the latest FreeUnit build is recommended. + + To migrate from NetBSD's Unit packages to FreeUnit: + + #. **Remove existing packages** + + .. code-block:: console + + # pkg_delete unit libunit unit-perl unit-python* unit-ruby* + + #. **Build FreeUnit from source** + + .. code-block:: console + + # pkg_add git openssl pcre2 libxslt + # git clone https://github.com/freeunitorg/freeunit + # cd freeunit + # ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 + # make + # make install + + #. **Set up service** + + .. code-block:: console + + # cp pkg/netbsd/unit /etc/rc.d/ + # echo "unit=YES" >> /etc/rc.conf + # service unit restart + + Runtime details: + + .. 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 + + .. warning:: + Nix packages for Unit may be outdated. + For security updates and PHP 8.3+ support, + migrating to the latest FreeUnit build is recommended. + + To migrate from Nix's Unit packages to FreeUnit: + + #. **Remove existing package** + + .. code-block:: console + + $ nix-env -e unit + + #. **Build FreeUnit from source** + + .. code-block:: console + + $ nix-env -iA nixpkgs.git nixpkgs.openssl nixpkgs.pcre2 + $ git clone https://github.com/freeunitorg/freeunit + $ cd freeunit + $ ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 + $ make + $ sudo make install + + #. **Set up systemd service** + + .. code-block:: console + + # cp pkg/systemd/unit.service /etc/systemd/system/ + # systemctl daemon-reload + # systemctl enable --now unit + + Runtime details: + + .. 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 + + .. warning:: + OpenBSD packages/ports for Unit may be outdated. + For security updates and PHP 8.3+ support, + migrating to the latest FreeUnit build is recommended. + + To migrate from OpenBSD's Unit packages to FreeUnit: + + #. **Remove existing packages** + + .. code-block:: console + + # pkg_delete unit unit-perl unit-php* unit-python unit-ruby + + #. **Build FreeUnit from source** + + .. code-block:: console + + # pkg_add git openssl pcre2 libxslt + # git clone https://github.com/freeunitorg/freeunit + # cd freeunit + # ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 + # make + # make install + + #. **Set up rcctl service** + + .. code-block:: console + + # cp pkg/openbsd/unit /etc/rc.d/ + # rcctl enable unit + # rcctl restart unit + + Runtime details: + + .. 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 + + .. warning:: + Remi's repository may provide outdated Unit packages. + For security updates and PHP 8.3+ support, + migrating to the latest FreeUnit build is recommended. + + To migrate from Remi's Unit packages to FreeUnit: + + #. **Keep Remi's PHP packages** (optional but recommended) + + FreeUnit's core is fully compatible with Remi's + ``phpXX-unit-php`` modules. You can continue using Remi + for PHP runtime packages while running FreeUnit as the core. + + #. **Disable Unit from Remi's repo** + + Prevent conflicts by excluding Unit packages from Remi: + + .. code-block:: ini + :caption: /etc/yum.repos.d/remi.repo + + [remi] + name=Remi's RPM repository + ... + exclude=unit* + + #. **Build FreeUnit core** + + .. code-block:: console + + # yum install git openssl-devel pcre2-devel libxslt-devel + # git clone https://github.com/freeunitorg/freeunit + # cd freeunit + # ./configure --openssl --prefix=/usr --modules=php:8.4,python:3.13 + # make + # make install + + .. note:: + Using ``--prefix=/usr`` ensures paths match Remi's package layout + (``/usr/sbin/unitd``, ``/usr/lib64/unit/modules/``, etc.). + + #. **Verify the installation** + + .. code-block:: console + + # /usr/sbin/unitd --version + freeunit/X.Y.Z # Example format; actual version may differ + + #. **Restart FreeUnit** + + .. code-block:: console + + # systemctl restart unit + + Runtime details: + + .. 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 +==== + +#. **Use FreeUnit's official image** + + Reference the image in your ``Dockerfile`` or ``docker-compose.yml``: + + .. code-block:: docker + :caption: Example usage + + FROM ghcr.io/freeunitorg/freeunit:latest + + .. note:: + FreeUnit images are hosted on GitHub Container Registry: + https://github.com/freeunitorg/freeunit/pkgs/container/freeunit + + Available tags: + + - ``latest`` — Full-featured image with all language modules + - ``minimal`` — Base image without language modules + - ``php`` — PHP-only variant + - ``python`` — Python-only variant + - ``nodejs`` — Node.js-only variant + - ``go`` — Go-only variant + - ``ruby`` — Ruby-only variant + - ``perl`` — Perl-only variant + - ``wasm`` — WebAssembly (WASI 0.2) support + + Version-pinned tags (examples): + - ``1.35.3``, ``1.35``, ``1`` — Core version only + - ``1.35.3-php``, ``1.35-php`` — PHP variant with version pin + - ``1.35.3-python``, ``1.35-python`` — Python variant + + Each tag is available for both ``amd64`` and ``arm64`` architectures. + Multi-arch manifests are automatically created on release. + +#. **Verify the image** + + .. code-block:: console + + $ docker run --rm ghcr.io/freeunitorg/freeunit:latest 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 # Previous pinned version + + 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 From 25575c6f2993f1176a3a95c26265e5ec3e51c4e0 Mon Sep 17 00:00:00 2001 From: Alexandr Smirnov Date: Sun, 19 Apr 2026 10:35:52 +0300 Subject: [PATCH 2/3] docs: rewrite migration and installation for FreeUnit fork MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit migration.rst: split guide into user vs. maintainer audiences; rewrite Community Repository Maintainers section with per-distro packaging recipes (Alpine, ALT, Arch, FreeBSD, Gentoo, NetBSD, Nix, OpenBSD, Remi RPM); fix Docker section — correct tag format (-), add full variant table from docker.yml (27 variants), add language EOL policy note, fix rollback example tag, fix verify command. installation.rst: add "coming soon" warnings for official packages, link to migration guide, update Docker section to GHCR registry with correct tag format and variant list, mark repo install script and Homebrew tap as archived/incompatible, fix all residual nginx/unit source URLs. --- source/installation.rst | 355 ++++++++------------- source/migration.rst | 662 ++++++++++++++++++++++++++-------------- 2 files changed, 549 insertions(+), 468 deletions(-) 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 index 30482498..76fb744e 100644 --- a/source/migration.rst +++ b/source/migration.rst @@ -1,6 +1,7 @@ .. meta:: :og:description: Migrate from archived Unit installations or community packages - to the community-maintained FreeUnit fork. + to the community-maintained FreeUnit fork, including maintainer guidance + for updating downstream packaging recipes. .. include:: include/replace.rst @@ -8,14 +9,20 @@ Migration ######### -This guide helps you migrate from archived Unit installations -or community-maintained packages to **FreeUnit**, -the community-maintained LTS fork. +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. - In most cases, migration requires only switching to a new build source - — no configuration changes needed. + 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.** @@ -28,19 +35,26 @@ the community-maintained LTS fork. Native package manager support (APT/YUM) is in active development. Track progress at: https://github.com/freeunitorg/freeunit/milestone/2 -You can migrate to FreeUnit in three alternative ways: +**For users** — pick one install path: - Run our :ref:`Docker official images `, - prepackaged with varied language combinations. + 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. + 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). + 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 @@ -48,9 +62,32 @@ You can migrate to FreeUnit in three alternative ways: .. _migration-community-repos: -****************************** -Community Repositories -****************************** +*********************************** +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, @@ -63,39 +100,43 @@ Community Repositories .. tab:: Alpine - .. warning:: - Alpine's Unit packages may be outdated. - For security updates and PHP 8.3+ support, - migrating to the latest FreeUnit build is recommended. + Recipe: ``community/unit/APKBUILD`` in + `alpinelinux/aports `_. - To migrate from Alpine's Unit packages to FreeUnit: + #. **Rename the aport** - #. **Remove existing Unit packages** + Move ``community/unit/`` to ``community/freeunit/`` and update + ``APKBUILD``: - .. code-block:: console + .. code-block:: sh + :caption: community/freeunit/APKBUILD - # apk del unit unit-openrc unit-perl unit-php* unit-python* unit-ruby + 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" - #. **Build FreeUnit from source** + #. **Refresh checksums** .. code-block:: console - # apk add build-base openssl-dev pcre2-dev libxslt-dev - # git clone https://github.com/freeunitorg/freeunit - # cd freeunit - # ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 - # make - # make install + $ abuild checksum - #. **Set up OpenRC service** + #. **Build and test** .. code-block:: console - # cp pkg/openrc/unit /etc/init.d/ - # rc-update add unit - # rc-service unit restart + $ abuild -r + + #. **Submit an MR** to aports following the + `Alpine contributing guide + `_. - Runtime details: + Runtime details (unchanged from the legacy ``unit`` aport): .. list-table:: @@ -110,39 +151,42 @@ Community Repositories .. tab:: ALT - .. warning:: - ALT Linux's Unit packages may be outdated. - For security updates and PHP 8.3+ support, - migrating to the latest FreeUnit build is recommended. - - To migrate from ALT's Unit packages to FreeUnit: + Recipe: ``unit.spec`` in the Sisyphus + `gears/u/unit + `_ repository. - #. **Remove existing Unit packages** + #. **Clone the gear and branch it** .. code-block:: console - # apt-get remove unit unit-perl unit-php unit-python3 unit-ruby + $ git clone git://git.altlinux.org/gears/u/unit.git freeunit + $ cd freeunit - #. **Build FreeUnit from source** + #. **Update the spec** - .. code-block:: console + .. code-block:: spec + :caption: freeunit.spec - # apt-get install build-essential libssl-dev libpcre2-dev libxslt1-dev - # git clone https://github.com/freeunitorg/freeunit - # cd freeunit - # ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 - # make - # make install + Name: freeunit + Version: 1.35.3 + Source0: https://github.com/freeunitorg/freeunit/archive/refs/tags/%version.tar.gz + Provides: unit = %EVR + Obsoletes: unit < %EVR - #. **Set up systemd service** + Rename subpackages the same way + (``unit-perl`` → ``freeunit-perl``, ``unit-php`` → ``freeunit-php``, …). + + #. **Rebuild in the hasher** .. code-block:: console - # cp pkg/systemd/unit.service /etc/systemd/system/ - # systemctl daemon-reload - # systemctl enable --now unit + $ 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: + Runtime details (unchanged from the legacy ``unit`` gear): .. list-table:: @@ -157,39 +201,55 @@ Community Repositories .. tab:: Arch - .. warning:: - Arch AUR Unit packages may be outdated. - For security updates and PHP 8.3+ support, - migrating to the latest FreeUnit build is recommended. + Recipe: ``PKGBUILD`` in the + `nginx-unit AUR package + `_. - To migrate from Arch's Unit packages to FreeUnit: + 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')``). - #. **Remove existing AUR package** + #. **Clone the AUR repo and rename** .. code-block:: console - # pacman -R unit + $ git clone ssh://aur@aur.archlinux.org/freeunit.git + $ cd freeunit + + #. **Update PKGBUILD** + + .. code-block:: sh + :caption: PKGBUILD - #. **Build FreeUnit from source** + 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 - # pacman -S base-devel openssl pcre2 libxslt - # git clone https://github.com/freeunitorg/freeunit - # cd freeunit - # ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 - # make - # make install + $ updpkgsums + $ makepkg --printsrcinfo > .SRCINFO - #. **Set up systemd service** + #. **Build in a clean chroot, then push** .. code-block:: console - # cp pkg/systemd/unit.service /etc/systemd/system/ - # systemctl daemon-reload - # systemctl enable --now unit + $ 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: + Runtime details (unchanged from the legacy ``nginx-unit`` AUR package): .. list-table:: @@ -204,39 +264,55 @@ Community Repositories .. tab:: FreeBSD - .. warning:: - FreeBSD ports/packages for Unit may be outdated. - For security updates and PHP 8.3+ support, - migrating to the latest FreeUnit build is recommended. + Recipe: the ``www/unit`` port in + `freebsd/freebsd-ports + `_. - To migrate from FreeBSD's Unit packages to FreeUnit: + Strategy: create a new slave-free port ``www/freeunit`` and mark the + old ``www/unit`` port deprecated with ``MOVED`` redirect. - #. **Remove existing packages** + #. **Copy the port tree** .. code-block:: console - # pkg remove unit libunit unit-php* unit-python* unit-ruby* + $ 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 - #. **Build FreeUnit from source** + #. **Update each Makefile** - .. code-block:: console + .. 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 - # pkg install git openssl pcre2 libxslt - # git clone https://github.com/freeunitorg/freeunit - # cd freeunit - # ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 - # make - # make install + USE_GITHUB= yes + GH_ACCOUNT= freeunitorg + GH_PROJECT= freeunit - #. **Set up service** + 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 - # cp pkg/freebsd/unitd /usr/local/etc/rc.d/ - # sysrc unitd_enable=YES - # service unitd restart + $ make makesum + + #. **Register the rename in ``MOVED``** + + .. code-block:: text - Runtime details: + 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:: @@ -251,40 +327,53 @@ Community Repositories .. tab:: Gentoo - .. warning:: - Gentoo ebuilds for Unit may be outdated. - For security updates and PHP 8.3+ support, - migrating to the latest FreeUnit build is recommended. + Recipe: ``www-servers/nginx-unit`` in the + `::gentoo tree `_. - To migrate from Gentoo's Unit packages to FreeUnit: + 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. - #. **Remove existing package** + #. **Create the new package directory** .. code-block:: console - # emerge --deselect www-servers/unit - # emerge --depclean + $ 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}" - #. **Build FreeUnit from source** + RDEPEND="!!`_ + per the `Gentoo developer manual + `_. - Runtime details: + Runtime details (unchanged from the legacy ``nginx-unit`` ebuild): .. list-table:: @@ -299,39 +388,51 @@ Community Repositories .. tab:: NetBSD - .. warning:: - NetBSD packages for Unit may be outdated. - For security updates and PHP 8.3+ support, - migrating to the latest FreeUnit build is recommended. - - To migrate from NetBSD's Unit packages to FreeUnit: + Recipe: ``www/unit`` in + `pkgsrc `_. - #. **Remove existing packages** + #. **Copy the category directory** .. code-block:: console - # pkg_delete unit libunit unit-perl unit-python* unit-ruby* + $ cd pkgsrc/www + $ cp -R unit freeunit + + #. **Update the Makefile** + + .. code-block:: make + :caption: www/freeunit/Makefile - #. **Build FreeUnit from source** + 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 - # pkg_add git openssl pcre2 libxslt - # git clone https://github.com/freeunitorg/freeunit - # cd freeunit - # ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 - # make - # make install + $ make distinfo - #. **Set up service** + #. **Test-build** .. code-block:: console - # cp pkg/netbsd/unit /etc/rc.d/ - # echo "unit=YES" >> /etc/rc.conf - # service unit restart + $ cd www/freeunit && make package - Runtime details: + #. **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:: @@ -346,39 +447,63 @@ Community Repositories .. tab:: Nix - .. warning:: - Nix packages for Unit may be outdated. - For security updates and PHP 8.3+ support, - migrating to the latest FreeUnit build is recommended. + Recipe: ``pkgs/servers/http/unit/default.nix`` in + `NixOS/nixpkgs `_. - To migrate from Nix's Unit packages to FreeUnit: + 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. - #. **Remove existing package** + #. **Rename the derivation directory** .. code-block:: console - $ nix-env -e unit + $ git mv pkgs/servers/http/unit pkgs/servers/http/freeunit - #. **Build FreeUnit from source** + #. **Update default.nix** - .. code-block:: console + .. code-block:: nix + :caption: pkgs/servers/http/freeunit/default.nix - $ nix-env -iA nixpkgs.git nixpkgs.openssl nixpkgs.pcre2 - $ git clone https://github.com/freeunitorg/freeunit - $ cd freeunit - $ ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 - $ make - $ sudo make install + 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 - #. **Set up systemd service** + 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 - # cp pkg/systemd/unit.service /etc/systemd/system/ - # systemctl daemon-reload - # systemctl enable --now unit + $ 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: + Runtime details (unchanged from the legacy ``unit`` derivation): .. list-table:: @@ -393,39 +518,59 @@ Community Repositories .. tab:: OpenBSD - .. warning:: - OpenBSD packages/ports for Unit may be outdated. - For security updates and PHP 8.3+ support, - migrating to the latest FreeUnit build is recommended. - - To migrate from OpenBSD's Unit packages to FreeUnit: + Recipe: ``www/unit`` in the + `OpenBSD ports tree + `_. - #. **Remove existing packages** + #. **Create the new port** .. code-block:: console - # pkg_delete unit unit-perl unit-php* unit-python unit-ruby + $ cd /usr/ports/www + $ cp -R unit freeunit - #. **Build FreeUnit from source** + #. **Update the Makefile** - .. code-block:: console + .. code-block:: make + :caption: www/freeunit/Makefile - # pkg_add git openssl pcre2 libxslt - # git clone https://github.com/freeunitorg/freeunit - # cd freeunit - # ./configure --openssl --modules=php:8.4,python:3.13,nodejs:22 - # make - # make install + 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} - #. **Set up rcctl service** + 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 - # cp pkg/openbsd/unit /etc/rc.d/ - # rcctl enable unit - # rcctl restart unit + $ 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 - Runtime details: + #. **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:: @@ -440,60 +585,67 @@ Community Repositories .. tab:: Remi's RPM - .. warning:: - Remi's repository may provide outdated Unit packages. - For security updates and PHP 8.3+ support, - migrating to the latest FreeUnit build is recommended. + 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. - To migrate from Remi's Unit packages to FreeUnit: + 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. - #. **Keep Remi's PHP packages** (optional but recommended) + #. **Fork the spec to ``freeunit.spec``** - FreeUnit's core is fully compatible with Remi's - ``phpXX-unit-php`` modules. You can continue using Remi - for PHP runtime packages while running FreeUnit as the core. + .. code-block:: spec + :caption: freeunit.spec - #. **Disable Unit from Remi's repo** + %global gh_owner freeunitorg + %global gh_project freeunit - Prevent conflicts by excluding Unit packages from Remi: + 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 - .. code-block:: ini - :caption: /etc/yum.repos.d/remi.repo + Provides: unit = %{version}-%{release} + Obsoletes: unit < %{version}-%{release} - [remi] - name=Remi's RPM repository - ... - exclude=unit* + %prep + %autosetup -n %{gh_project}-%{version} - #. **Build FreeUnit core** + 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``. - .. code-block:: console + #. **Update ``phpXX-unit-php`` sub-specs** - # yum install git openssl-devel pcre2-devel libxslt-devel - # git clone https://github.com/freeunitorg/freeunit - # cd freeunit - # ./configure --openssl --prefix=/usr --modules=php:8.4,python:3.13 - # make - # make install + No rename required — only bump their + ``BuildRequires: freeunit-devel >= %{version}`` / + ``Requires: freeunit >= %{version}`` lines so they link against + the renamed core. - .. note:: - Using ``--prefix=/usr`` ensures paths match Remi's package layout - (``/usr/sbin/unitd``, ``/usr/lib64/unit/modules/``, etc.). - - #. **Verify the installation** + #. **Build and hand the SRPM to Remi** .. code-block:: console - # /usr/sbin/unitd --version - freeunit/X.Y.Z # Example format; actual version may differ + $ rpmbuild -ba freeunit.spec - #. **Restart FreeUnit** + 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 - # systemctl restart unit + # dnf upgrade freeunit + # /usr/sbin/unitd --version + freeunit/1.35.3 - Runtime details: + Runtime details (unchanged from the legacy ``unit`` RPM): .. list-table:: @@ -520,44 +672,80 @@ FreeUnit provides official Docker images for easy deployment. Steps ==== -#. **Use FreeUnit's official image** +#. **Pick a tag and reference it** - Reference the image in your ``Dockerfile`` or ``docker-compose.yml``: + Images are hosted on GitHub Container Registry (GHCR): + https://github.com/freeunitorg/freeunit/pkgs/container/freeunit - .. code-block:: docker - :caption: Example usage + 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. - FROM ghcr.io/freeunitorg/freeunit:latest + * - ``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:: - FreeUnit images are hosted on GitHub Container Registry: - https://github.com/freeunitorg/freeunit/pkgs/container/freeunit + **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 - Available tags: + Reference the image in your ``Dockerfile`` or ``docker-compose.yml``: - - ``latest`` — Full-featured image with all language modules - - ``minimal`` — Base image without language modules - - ``php`` — PHP-only variant - - ``python`` — Python-only variant - - ``nodejs`` — Node.js-only variant - - ``go`` — Go-only variant - - ``ruby`` — Ruby-only variant - - ``perl`` — Perl-only variant - - ``wasm`` — WebAssembly (WASI 0.2) support + .. code-block:: docker + :caption: Example — pinning PHP 8.4 - Version-pinned tags (examples): - - ``1.35.3``, ``1.35``, ``1`` — Core version only - - ``1.35.3-php``, ``1.35-php`` — PHP variant with version pin - - ``1.35.3-python``, ``1.35-python`` — Python variant + FROM ghcr.io/freeunitorg/freeunit:1.35.3-php8.4 + + .. code-block:: docker + :caption: Example — rolling latest Python 3.13 - Each tag is available for both ``amd64`` and ``arm64`` architectures. - Multi-arch manifests are automatically created on release. + FROM ghcr.io/freeunitorg/freeunit:latest-python3.13 #. **Verify the image** .. code-block:: console - $ docker run --rm ghcr.io/freeunitorg/freeunit:latest unitd --version + $ docker run --rm ghcr.io/freeunitorg/freeunit:latest-minimal unitd --version freeunit/X.Y.Z # Example format; actual version may differ .. note:: @@ -823,7 +1011,7 @@ If you need to revert to the previous setup: .. code-block:: docker - FROM ghcr.io/freeunitorg/freeunit:1.35.0 # Previous pinned version + FROM ghcr.io/freeunitorg/freeunit:1.35.0-php8.4 # Previous pinned version; replace variant to match your image Then redeploy: From d5e797dfc62c8e59daaa164e421f01b03cb88629 Mon Sep 17 00:00:00 2001 From: Alexandr Smirnov Date: Mon, 20 Apr 2026 23:26:48 +0300 Subject: [PATCH 3/3] docker: Build local for test --- .gitignore | 2 ++ Dockerfile.local | 14 ++++++++++++++ README.md | 8 ++++++++ 3 files changed, 24 insertions(+) create mode 100644 Dockerfile.local 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.