feat(wolf-search): 6-f.2 packaging half — wolf-search.deb, five .debs, CI installs + health-checks it (closes 6-f.2)

debian/wolf-search.* mirroring wolf-database: the .deb ships only
Wolf-owned artifacts (wrapper + settings/uwsgi templates + dedicated
unit); postinst = the exact 6-f.2 host recipe pinned to 747cec4c
(searxng user, clone at the pin, searx-pyenv + official pip sequence,
per-host secret install-once root:searxng 640, ini to apps-available
never apps-enabled). Requires network at install — ratified ADR 0032
trade-off; air-gapped installs skip it (Recommends in the wolf
meta-package, not Depends). Upgrades incremental; remove keeps
/etc/searxng until purge; searxng user never removed.

CI: smoke-deb + release.yml expect five .debs; smoke-deb-install
installs wolf-search, asserts every postinst effect, then starts the
service and runs `wolf-search health` end-to-end (timeout 15→25);
smoke-systemd verifies the 4th unit template. Docs: RELEASING,
docs/17, ONBOARDING topology + sideload, roadmap 6-f.2 ✅, ADR 0032
addendum + Appendix A → the real postinst.

Next: 6-f.3 — web_search/web_fetch/bounded web_crawl tools + A6
security + docs-first + citations, gated on WEB_SEARCH_ENABLED.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: alsechemist

.github/workflows/ci.yml

@@ -467,9 +467,10 @@ jobs:
   # syntactic + presence-of-fail-loud-branches validation. Catches
   # regressions in unit-file syntax, shim shell logic, and the
   # install.sh CLI surface.
-  # Phase 5.9-e: build all four wolf-*.deb on a clean ubuntu-latest
-  # runner. Catches build-time issues across the per-component
-  # debian/ artifacts authored in 5.9-a/b/c/d that the per-slice
+  # Phase 5.9-e: build all five wolf-*.deb on a clean ubuntu-latest
+  # runner (wolf-search joined in slice 6-f.2, ADR 0032). Catches
+  # build-time issues across the per-component debian/ artifacts
+  # authored in 5.9-a/b/c/d + 6-f.2 that the per-slice
   # static checks (bash -n, syntax-only validation) can't reach.
   # Runs natively on the runner (vs Docker-in-Docker) — faster, no
   # nested-container quirks.
@@ -511,7 +512,7 @@ jobs:
             python3 python3-pip python3-venv python3-build \
             nodejs npm \
             ca-certificates
-      - name: Build all four .debs
+      - name: Build all five .debs
         run: dpkg-buildpackage -b -us -uc
       - name: Stage .debs inside the workspace for upload
         # dpkg-buildpackage drops .deb files in the parent of the
@@ -522,8 +523,8 @@ jobs:
           mv ../wolf*.deb packaging/build/debs/
           ls -la packaging/build/debs/
           count=$(ls packaging/build/debs/wolf*.deb 2>/dev/null | wc -l)
-          if [ "$count" -lt 4 ]; then
-            echo "FAIL: expected 4 .debs, got $count"
+          if [ "$count" -lt 5 ]; then
+            echo "FAIL: expected 5 .debs, got $count"
             exit 1
           fi
           echo "OK: $count .debs produced"
@@ -632,7 +633,9 @@ jobs:
     # NodeSource). add-apt-repository ppa:deadsnakes can hang on a slow
     # launchpad/keyserver — with no timeout it wedges at GitHub's 6-hour
     # default. Cap it so an infra hang fails fast in minutes, not hours.
-    timeout-minutes: 15
+    # 25 (was 15): wolf-search's postinst clones SearXNG + pip-installs
+    # its deps over the network (~3-5 min on a runner) — slice 6-f.2.
+    timeout-minutes: 25
     steps:
       - uses: actions/checkout@v6
       - name: Download .debs from smoke-deb
@@ -683,16 +686,21 @@ jobs:
           sudo apt-get install -y python3.13 python3.13-venv nodejs
           python3.13 --version
           node --version
-      - name: Install all four wolf-*.debs
+      - name: Install all five wolf-*.debs
         # apt install resolves the inter-package deps automatically
         # (wolf-server depends on wolf-database, the meta wolf
-        # depends on all three components, etc.).
+        # depends on all three components, etc.). wolf-search's
+        # Depends (uwsgi, git, libxslt-dev, ...) come from stock
+        # noble; its postinst clones SearXNG at the Wolf-verified
+        # pin + builds the venv — real network install, by design
+        # (ADR 0032: the postinst IS the official install recipe).
         run: |
           ls -la debs/
           sudo apt install -y \
               ./debs/wolf-database_*.deb \
               ./debs/wolf-server_*.deb \
               ./debs/wolf-dashboard_*.deb \
+              ./debs/wolf-search_*.deb \
               ./debs/wolf_*.deb
       - name: Verify service users + group created by postinst
         run: |
@@ -752,11 +760,12 @@ jobs:
           /usr/bin/wolf-cert --help 2>&1 | head -5
           echo "OK: shims executable + CLIs respond"
       - name: Verify systemd units are loaded
-        # Don't start them (needs operator-driven init); just
-        # confirm systemd recognises the units so they could be
-        # started.
+        # Don't start the three core components (needs operator-driven
+        # init); just confirm systemd recognises the units so they
+        # could be started. wolf-search gets a REAL start below — it
+        # is the one component whose postinst leaves it fully runnable.
         run: |
-          for unit in wolf-database wolf-server wolf-dashboard; do
+          for unit in wolf-database wolf-server wolf-dashboard wolf-search; do
               systemctl status "$unit" --no-pager 2>&1 | head -3 || true
               # `is-enabled` returns "disabled" for fresh installs
               # (postinst doesn't auto-enable; operator does that
@@ -765,12 +774,59 @@ jobs:
               systemctl cat "$unit" >/dev/null 2>&1 \
                   || { echo "FAIL: systemctl can't load $unit unit"; exit 1; }
           done
-          echo "OK: all 3 systemd units loaded + parseable"
+          echo "OK: all 4 systemd units loaded + parseable"
+      - name: Verify wolf-search postinst effects (slice 6-f.2)
+        # The postinst = the official SearXNG recipe pinned to the
+        # Wolf-verified commit. Verify each of its jobs actually
+        # happened on this clean runner.
+        run: |
+          getent passwd searxng || { echo "FAIL: searxng user missing"; exit 1; }
+          pin="747cec4c2304fc2e06ceb4a46dbe25bfb769db1e"
+          head=$(sudo -u searxng git -C /usr/local/searxng/searxng-src rev-parse HEAD)
+          [ "$head" = "$pin" ] \
+              || { echo "FAIL: searxng-src at $head, expected pin $pin"; exit 1; }
+          test -x /usr/local/searxng/searx-pyenv/bin/python \
+              || { echo "FAIL: searx-pyenv venv missing"; exit 1; }
+          perms=$(stat -c "%a %U %G" /etc/searxng/settings.yml)
+          [ "$perms" = "640 root searxng" ] \
+              || { echo "FAIL: settings.yml is '$perms', expected '640 root searxng'"; exit 1; }
+          if sudo grep -q "ultrasecretkey" /etc/searxng/settings.yml; then
+              echo "FAIL: secret_key placeholder not substituted"; exit 1
+          fi
+          test -f /etc/uwsgi/apps-available/searxng.ini \
+              || { echo "FAIL: uwsgi ini missing"; exit 1; }
+          if test -L /etc/uwsgi/apps-enabled/searxng.ini; then
+              echo "FAIL: ini must NOT be in apps-enabled (double-run)"; exit 1
+          fi
+          test -x /usr/bin/wolf-search || { echo "FAIL: wolf-search shim missing"; exit 1; }
+          /usr/bin/wolf-search help | grep -q "health" \
+              || { echo "FAIL: wolf-search help doesn't list health"; exit 1; }
+          echo "OK: searxng user + pinned checkout + venv + settings(640) + ini + shim"
+      - name: Start wolf-search + end-to-end health check
+        # Unlike the three core components, wolf-search needs no
+        # operator-provisioned env — postinst leaves it runnable.
+        # `wolf-search health` probes the exact JSON endpoint
+        # wolf-server's SearxngProvider consumes; SearXNG answers
+        # HTTP 200 regardless of upstream-engine luck, so this is
+        # stable on a datacenter runner.
+        run: |
+          sudo systemctl start wolf-search
+          for i in $(seq 1 12); do
+              if /usr/bin/wolf-search health; then
+                  echo "OK: wolf-search healthy end-to-end (loopback 1307, JSON API 200)"
+                  exit 0
+              fi
+              sleep 5
+          done
+          echo "FAIL: wolf-search not healthy after 60s"
+          sudo journalctl -u wolf-search --no-pager | tail -40
+          exit 1
       - name: Smoke summary
         run: |
           echo "=== smoke-deb-install: PASS ==="
           echo "wolf-* packages installed cleanly on ubuntu-latest"
           echo "users / group / FHS dirs / venvs / shims / systemd units all verified"
+          echo "wolf-search: postinst recipe verified + service started + health OK"
 
   smoke-systemd:
     name: systemd + shims smoke (Phase 5.8-d)

.github/workflows/release.yml

@@ -8,7 +8,7 @@ name: Release
 #   git push origin v0.X.Y
 #
 # What happens:
-#   1. Build the four wolf-*.deb files (same as smoke-deb).
+#   1. Build the five wolf-*.deb files (same as smoke-deb).
 #   2. Sign each .deb with the Wolf maintainers' GPG key.
 #   3. Produce SHA256SUMS + sign that too.
 #   4. Create a GitHub Release at https://github.com/M-s-Tech4TIME/
@@ -80,16 +80,16 @@ jobs:
             nodejs npm \
             ca-certificates
 
-      - name: Build all four .debs
+      - name: Build all five .debs
         run: dpkg-buildpackage -b -us -uc
 
       - name: Stage .debs inside the workspace
         run: |
           mkdir -p packaging/build/debs
           mv ../wolf*.deb packaging/build/debs/
           count=$(ls packaging/build/debs/wolf*.deb 2>/dev/null | wc -l)
-          if [ "$count" -lt 4 ]; then
-            echo "FAIL: expected 4 .debs, got $count"
+          if [ "$count" -lt 5 ]; then
+            echo "FAIL: expected 5 .debs, got $count"
             exit 1
           fi
           echo "OK: ${count} .debs produced for ${{ steps.version.outputs.version }}"

Makefile

@@ -254,18 +254,19 @@ smoke-systemd: ## End-to-end systemd + shim smoke (Phase 5.8-d)
 		echo "    OK: all three installed user units are clean"; \
 		\
 		echo "--- 3/5: systemd-analyze passes on system-level unit templates ---"; \
-		echo "    (filtering expected \"/usr/bin/wolf-* is not executable\"; that lands with the .deb)"; \
+		echo "    (filtering expected \"... is not executable\"; binaries land with the .debs)"; \
 		for u in deploy/systemd/system/wolf-database.service \
 		         deploy/systemd/system/wolf-server.service \
-		         deploy/systemd/system/wolf-dashboard.service; do \
+		         deploy/systemd/system/wolf-dashboard.service \
+		         deploy/systemd/system/wolf-search.service; do \
 		  out=$$(systemd-analyze verify --man=no "$$u" 2>&1 | \
 		    grep -v "is not executable" || true); \
 		  if [ -n "$$out" ]; then \
 		    echo "FAIL: $$u has unexpected issues:"; \
 		    echo "$$out"; exit 1; \
 		  fi; \
 		done; \
-		echo "    OK: all three system unit templates have clean directives"; \
+		echo "    OK: all four system unit templates have clean directives"; \
 		\
 		echo "--- 4/5: every shim fails loud with exit 2 when its venv is missing ---"; \
 		for shim in deploy/bin/wolf-cert deploy/bin/wolf-database \

ONBOARDING.md

@@ -736,6 +736,7 @@ threat model.
                   │ wolf-server host       │
                   │ (internal "brain" VLAN)│
                   │  - wolf-server.deb     │
+                  │  - wolf-search.deb**   │
                   └───────────┬────────────┘
                               │ Wazuh API
                               ▼
@@ -745,6 +746,11 @@ threat model.
 
 * wolf-database can live on either host. Most operators
   co-locate it with wolf-server (less network surface).
+** wolf-search (SearXNG web research, ADR 0032) is
+  wolf-server's sidecar: ALWAYS co-located with wolf-server,
+  loopback-only (127.0.0.1:1307) — in every topology. Optional:
+  skip it (it's a Recommends) for air-gapped installs or
+  hosted search backends.
 ```
 
 **Three-host topology (brain + edge + DB):**
@@ -770,9 +776,12 @@ wolf-database first (it owns the schema), then wolf-server
 
 ```bash
 # 1. Add the Wolf APT repository (URL pending; tracked as
-#    docs/17 gap 2). Until then, sideload the .deb files:
+#    docs/17 gap 2). Until then, sideload the .deb files.
+#    wolf-search is optional-but-default (web research; its
+#    postinst needs network to github.com + PyPI):
 sudo apt install ./wolf-database_0.1.0_amd64.deb \
-                 ./wolf-server_0.1.0_amd64.deb
+                 ./wolf-server_0.1.0_amd64.deb \
+                 ./wolf-search_0.1.0_all.deb
 
 # 2. Initialize the cluster (one-shot):
 sudo -u wolf-database \

RELEASING.md

@@ -12,15 +12,16 @@ A "release" is:
 
 1. A git tag of the form `vMAJOR.MINOR.PATCH` (semver, see
    [SUPPORT.md](SUPPORT.md)).
-2. Four signed `.deb` files attached as assets to a GitHub
+2. Five signed `.deb` files attached as assets to a GitHub
    Release with that tag's name:
    - `wolf-database_X.Y.Z_amd64.deb`
    - `wolf-server_X.Y.Z_amd64.deb`
    - `wolf-dashboard_X.Y.Z_amd64.deb`
+   - `wolf-search_X.Y.Z_all.deb` (SearXNG sidecar, ADR 0032)
    - `wolf_X.Y.Z_all.deb` (meta-package)
 3. Detached signatures (`*.asc`) alongside each `.deb`.
 4. A signed `SHA256SUMS` (+ `SHA256SUMS.asc`) covering all
-   four `.deb` files.
+   five `.deb` files.
 5. Release notes pulled from `docs/CHANGELOG.md` (or a
    fallback if no matching section exists).
 
@@ -108,7 +109,7 @@ Pushing the tag triggers `.github/workflows/release.yml`,
 which:
 
 1. Verifies the tag version matches `debian/changelog`.
-2. Builds all four `.deb` files via `dpkg-buildpackage`.
+2. Builds all five `.deb` files via `dpkg-buildpackage`.
 3. Imports the Wolf signing key from `GPG_PRIVATE_KEY`
    secret + signs each `.deb` (detached `.asc` signature).
 4. Generates `SHA256SUMS` + signs that too.
@@ -133,8 +134,8 @@ v0.X.Y` to the release being live.
 Run this once the release workflow completes:
 
 ```bash
-# 1. Confirm the release exists with all 9 expected assets
-#    (4 .debs + 4 .asc + SHA256SUMS + SHA256SUMS.asc = 10).
+# 1. Confirm the release exists with all 12 expected assets
+#    (5 .debs + 5 .asc + SHA256SUMS + SHA256SUMS.asc = 12).
 gh release view v0.X.Y
 
 # 2. Download + verify locally as an operator would.

debian/control

@@ -73,18 +73,57 @@ Description: Wolf edge component (Next.js)
  Built from Next.js 16 with output: "standalone" so production
  doesn't need npm at runtime — just node.
 
+Package: wolf-search
+Architecture: all
+Depends:
+ ${misc:Depends},
+ python3-dev,
+ python3-babel,
+ python3-venv,
+ python-is-python3,
+ uwsgi,
+ uwsgi-plugin-python3,
+ git,
+ build-essential,
+ libxslt-dev,
+ zlib1g-dev,
+ libffi-dev,
+ libssl-dev,
+ openssl,
+ curl,
+ ca-certificates,
+Description: Wolf bundled-SearXNG component (loopback metasearch)
+ wolf-search wraps a SearXNG metasearch instance installed per the
+ official SearXNG Ubuntu/Debian step-by-step docs, pinned to a
+ Wolf-verified upstream commit. It is wolf-server's sidecar for the
+ web-research tools (ADR 0032): loopback-only on 127.0.0.1:1307,
+ called by nothing but wolf-server, no accounts, no API keys, no
+ per-query cost.
+ .
+ The Depends list is the official SearXNG install's apt list —
+ postinst executes that exact recipe (git clone at the pinned
+ commit + dedicated venv under /usr/local/searxng), so installing
+ this package REQUIRES network access to github.com and PyPI.
+ Air-gapped installs skip wolf-search (it is a Recommends of the
+ wolf meta-package, not a Depends) and use a hosted search backend
+ or none.
+
 Package: wolf
 Architecture: all
 Depends:
  ${misc:Depends},
  wolf-database (= ${binary:Version}),
  wolf-server (= ${binary:Version}),
  wolf-dashboard (= ${binary:Version}),
+Recommends:
+ wolf-search (= ${binary:Version}),
 Description: Wolf — agentic AI for Wazuh (all-in-one meta-package)
- Installs all three Wolf components on a single host. Convenience
- meta-package for the common all-in-one deployment; distributed
- deployments install the individual component packages on each
- host instead.
+ Installs all three core Wolf components on a single host, plus
+ wolf-search (SearXNG web research) as a Recommends — installed by
+ default, skippable via --no-install-recommends for air-gapped or
+ hosted-search-backend deployments. Convenience meta-package for
+ the common all-in-one deployment; distributed deployments install
+ the individual component packages on each host instead.
  .
  After installation, see /usr/share/doc/wolf/README for the
  one-command bring-up: wolf-database init + wolf-cert init +

debian/wolf-search.dirs

@@ -0,0 +1,9 @@
+# Empty directories the package ships. Mirrors wolf-database.dirs.
+#
+# /usr/local/searxng + /etc/searxng are NOT listed here — the
+# postinst is the canonical owner of those paths (it executes the
+# official SearXNG install recipe, which creates them with the
+# right ownership); having debhelper also create them would be a
+# coordination footgun.
+
+usr/lib/wolf-search

debian/wolf-search.install

@@ -0,0 +1,22 @@
+# debian/wolf-search.install — what ends up inside wolf-search.deb.
+#
+# Format: <source path relative to repo>  <install dir under debian/wolf-search/>
+#
+# The .deb itself carries only the Wolf-owned artifacts: the CLI
+# wrapper + the two config templates + the systemd unit (shipped via
+# debian/wolf-search.service). SearXNG itself is NOT in the .deb —
+# the postinst installs it per the official recipe (git clone pinned
+# to the Wolf-verified commit + venv under /usr/local/searxng),
+# exactly as the 6-f.2 host standup did by hand.
+
+# The operator CLI (health/status/version/logs/service ops). Same
+# script the manual install drops; the .deb ships it directly.
+deploy/bin/wolf-search  usr/bin/
+
+# Config templates. postinst installs each to its /etc destination
+# ONLY if absent (operator edits survive upgrades):
+#   settings.yml       -> /etc/searxng/settings.yml (+ per-host
+#                         secret_key via openssl, root:searxng 640)
+#   searxng-uwsgi.ini  -> /etc/uwsgi/apps-available/searxng.ini
+deploy/searxng/settings.yml       usr/lib/wolf-search/
+deploy/searxng/searxng-uwsgi.ini  usr/lib/wolf-search/