docs: add migration guide

[phpclub]

• New migration.rst with Docker, source build, and community repo instructions
• Compatible with FreeUnit v1.35.3+
• Follows installation.rst style guide

[andypost]

Review: docs: add migration guide

Overall: the structure is excellent — clear audience separation, comprehensive per-distro recipes, and good rollback/FAQ sections. However there are several factual inaccuracies that would mislead users.

---

Critical — Factual Errors

1. unitd --version does NOT output freeunit/X.Y.Z

NXT_NAME is still "Unit" in src/nxt_main.h:14 — the rebrand commit (297d5906) changed Dockerfile labels, README, etc. but never touched the C source. The actual output is Unit/1.35.2. This claim appears 6+ times throughout the PR (Docker verify, source build verify, FAQ, Remi verify).

Either the docs need to match reality (unit/X.Y.Z), or NXT_NAME needs changing in the C source first.

2. ./configure --modules=php:8.4,python:3.13,... does not exist

The source build section shows:

$ ./configure --openssl --otel \
     --modules=php:8.4,python:3.13,nodejs:22,go1.25,ruby3.4,perl5.40

--modules=DIR is a deprecated synonym for --modulesdir (sets the module install directory). Language modules are configured via separate subcommands:

$ ./configure --openssl
$ ./configure python --config=python3-config --module=python3
$ ./configure php --module=php
$ make
$ make python3 php

3. Broken internal link: migration-remi-hybrid

Referenced in the introduction and FAQ but the anchor is never defined. Will render as a broken cross-reference in Sphinx.

4. unitd --test-config does not exist

Used in the PHP troubleshooting section but this flag doesn't exist in Unit's CLI parser (src/nxt_main.c). Config validation happens through the control API, not a CLI flag.

5. make install does NOT install unitctl

The build section claims make install installs unitctl to /usr/local/bin/. The Makefile's install target only runs unitd-install + manpage-install. unitctl is built separately with cargo from tools/unitctl/.

6. pkg/systemd/unit.service does not exist

The systemd setup section says cp pkg/systemd/unit.service /etc/systemd/system/ but there is no pkg/systemd/ directory in the repo.

---

Significant — Incorrect Docker Variant Claims

The variant table lists go1.26 and node24, but only these Dockerfiles actually exist:

• go1.24, go1.25 (no go1.26)
• node20, node22 (no node24)
• ruby3.4 ✓, perl5.40 ✓, php8.5 ✓ — these are correct

Also: the custom Docker image section uses FROM ...:minimal but earlier the doc states there is "no bare latest tag". Should be latest-minimal or a pinned version.

---

Minor Issues

• docker-compose (v1 syntax) — modern Docker uses docker compose (v2 plugin, no hyphen). Consider using the v2 form.
• Runtime Compatibility table — Lists /run/unit/control.sock but the default from ./configure is $runstatedir/control.unit.sock (typically /run/unit/control.unit.sock).
• Duplicate Docker variant table — Identical table in both installation.rst and migration.rst. Consider using a shared include or cross-reference to avoid drift.
• Missing newline at EOF — migration.rst doesn't end with a newline.

[andypost]

Pedantic review

Reproduced locally with uv venv && uv pip install -r requirements.txt && .venv/bin/sphinx-build -E -b nxt_html source build — build succeeds but emits 47 warnings, all in source/migration.rst.

Blockers

1. Page not in toctree. source/contents.rst has no migration entry → WARNING: document isn't included in any toctree. The new page is orphaned from the sidebar.

2. Invalid .. meta:: directive (l. 1). Option fields (:og:description:) are indented 1 space; Sphinx needs ≥ 3. ERROR: Invalid meta directive. The OG description is silently dropped.

3. Unescaped *BSD (l. 16). * opens RST emphasis that never closes → WARNING: Inline emphasis start-string without end-string. Use \*BSD or *BSD*.

4. Undefined cross-references (41 warnings). None of these labels exist anywhere in source/:

   • socket, file, user and group — 10 :ref: each across the per-distro runtime-details tables. installation.rst uses explicit targets like socket <sec-socket>, file <troubleshooting-log>, user and group <security-apps>. The bare forms don't resolve.
   • tls, regex (l. 819–820) — upstream uses <configuration-ssl> and <configuration-routes-matching-patterns-regex>.
   • migration-remi-hybrid (l. 48, l. 1097) — the intro bullets and the FAQ promise a hybrid-approach section, but no .. _migration-remi-hybrid: label is defined.

5. Broken :doc: target (l. 1141). :doc:\configuration`→WARNING: unknown document: 'configuration'. The real path is configuration/index(seecontents.rst`).

6. Under-length section adornments (RST needs underlines ≥ title length):

   • l. 671 Steps (5) under ==== (4)
   • l. 765 Custom Images (13) under ==== (4)
   • l. 786 Build FreeUnit from Source (26) under **** (16)
   • l. 825 Build and Install FreeUnit (26) under ==== (4)
   • l. 914 Troubleshooting FreeUnit (24) under **** (16)
   • l. 991 Rollback Procedure (18) under **** (16)

7. Fabricated ./configure syntax (l. 842-843).

   $ ./configure --openssl --otel \
        --modules=php:8.4,python:3.13,nodejs:22,go1.25,ruby3.4,perl5.40
   

   There is no --modules= flag. Per auto/modules/ and the root CLAUDE.md, the real pattern is a separate ./configure <module> --module=… invocation per language, then make <module>. A user copy-pasting this hits unknown option immediately.

Significant

8. Version drift. conf.py has version = '1.35.3'; migration.rst hard-codes 1.35.3 in ~15 places (pkgvers, FROM tags, git checkout 1.35.0 in rollback). These won't track future bumps. Use |version| inside subs-code-block:: (pattern already in installation.rst l. 2094-2119) for the non-rollback examples.

9. Runtime Compatibility table contradicts itself (l. 895-910). It claims /run/unit/control.sock is "unchanged" — but the per-distro tables immediately above list five different socket paths. "Unchanged" is true per-distro only; phrase it that way.

10. Docker variant table — unverified against docker.yml. The commit message says the 27-variant table matches docker.yml in the freeunit repo, but this wasn't cross-checked. Before merging, diff against what actually builds, especially: go1.26 (Go 1.26 ships ~Feb 2026 — is it built?), python3.14-slim, node24, perl5.40, ruby3.4, jsc21.

Minor / nits

• sitemapexclude.txt not updated — decide explicitly whether migration.html should be indexed.
• freeunit/X.Y.Z # Example format; actual version may differ appears three times (l. 749, 887, 1108); pick one canonical location.
• l. 85 "upstream does not enforce a layout, so distro defaults are preserved" — slightly misleading; Unit's ./configure has its own defaults (/usr/local/…). Rephrase as "distro overrides at configure-time are preserved."
• l. 490 (Nix alias comment): # renamed 2026-04, remove after 25.11 — NixOS release numbering is YY.MM, so 25.11 is past. Should be 26.11 or 27.05.
• l. 310 (FreeBSD MOVED): hard-codes 2026-04-19 in an example block without a <DATE> placeholder.
• l. 343 (Gentoo): git mv nginx-unit-1.34.2.ebuild freeunit-1.35.3.ebuild assumes 1.34.2 was the last ebuild; verify against ::gentoo.
• l. 618: Leave --prefix=/usr in %configure — the %configure macro sets that automatically on Fedora/RHEL; redundant.
• l. 1133: http://freeunit.org/media/keys/6C68B7AA.asc — http, not https. Makefile l. 9 uses https for the same URL.
• FAQ (l. 1121-1127) points at milestone/3; intro warning (l. 36) points at milestone/2. Confirm both exist.
• Old unit-php7 / unit-python3.12 references remain in installation.rst archived sections — fine as reference, but add a per-section warning (deep-linked anchors skip the top-level one).

Not an issue (investigated)

• Tab-directive indentation. The 1-space indent throughout the Community Repository Maintainers tabs is stylistically inconsistent with installation.rst's 3-space indent, but the tabs extension is tolerant — no structural warnings emitted.

Reproduce locally

$ uv venv
$ uv pip install -r requirements.txt
$ .venv/bin/sphinx-build -E -b nxt_html source build

Verdict

Don't merge as-is. Blockers 1–7 either break the build (ERROR), drop content silently (meta/emphasis), or produce dangling refs. Blocker 7 in particular will mislead users who copy-paste.

Recommended path: fix the .. meta:: indent, escape *BSD, add migration to the toctree, switch the bare :ref: targets to the explicit <target> form used in installation.rst, fix the adornments, correct :doc:\configuration/index`, replace the fake --modules=line with the real per-module pattern. Runsphinx-build` locally and confirm zero warnings before re-requesting review.

[andypost]

I will try to fix some later today or tomorrow