Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

docs(air-gapped): the cleanup round 12 promised did not run on the paths it described

xerj-orgaa04fef7a3dc
diff --git a/docs/recipes/air-gapped-deployment.md b/docs/recipes/air-gapped-deployment.md
index 243cf6186..d2ce4972d 100644
--- a/docs/recipes/air-gapped-deployment.md
+++ b/docs/recipes/air-gapped-deployment.md
@@ -93,9 +93,9 @@ The following stages the Linux x86_64 musl archive only.
< <(tr -d '\r' < "$ASSET.sha256")
tar -xzf "$ASSET"
+ trap 'rm -rf "$OUT/release/$STAGE"' EXIT
test -x "$STAGE/xerj"
"$STAGE/xerj" --version
- rm -rf "$STAGE"
echo "staged $ASSET ($want) in $OUT"
)
```
@@ -108,11 +108,21 @@ evidence separately; `.sha256` alone does not provide it.
`"$STAGE/xerj" --version` executes the staged binary, so this block wants a
staging host of the same platform as the target — Linux x86_64 for the archive
-above. On any other staging host that one line fails, the block stops, and
-nothing is staged; drop it, or set `TARGET` to the triple you are actually
-staging. The extracted tree is removed either way: only the archive and its
-`.sha256` should cross the airgap, so that no unverified binary travels beside
-the verified one.
+above. On any other staging host that one line fails and the block stops with
+the archive and its `.sha256` already downloaded; either drop the line, or stage
+a different target, which means changing `TARGET` here **and** the triple
+written into `STAGE` in the enclave block below, because that one is spelled out
+rather than derived.
+
+The extracted tree is removed by the `trap`, on every exit path including those
+two failures — only the archive and its `.sha256` should cross the airgap, so
+that no unverified binary travels beside the verified one. The `trap` is what
+makes that true: an earlier version of this page ran `rm -rf` as the last line
+of the block and claimed the tree was "removed either way", which was false
+precisely on the wrong-platform path the sentence was written for — `set -e`
+ended the subshell at the failing line and never reached the `rm`. Measured at
+the time: exec-format failure `rc=126`, missing exec bit `rc=1`, non-zero exit
+`rc=7`, tree left behind in all three, removed only on success.
**Transfer `$OUT` itself, and land it in the enclave at `/opt/xerj-staging`**,
so that the archive is at `/opt/xerj-staging/release/` — that is the path the
@@ -185,10 +195,12 @@ form: with errexit gone, a failed `grep -qxF` no longer stops `tar -xzf`, and
the block extracts and runs the archive it just refused. Inside, a failure ends
the subshell and the operator keeps their session, so that pressure never
arises. Every block on this page that decides something now has its `set -eu`
-inside its own parentheses; the two that must leave variables behind for a later
-paste — the verification blocks in section 4 — carry no `set -eu` at all, and
-use `curl -fsS`, which reports its own failures without arming errexit in the
-operator's session.
+inside its own parentheses. The blocks that must leave variables behind for a
+later paste — section 4's checks, which set `KEY` and `XERJ`, and the `wal_tap`
+block that reads `KEY` — carry no `set -eu` at all. Every command in them is a
+`curl -fsS` or an assignment, so each reports its own failure without arming
+errexit in the operator's session, and none of them decides whether anything
+gets installed.
**The archive is copied once, then hashed and extracted from that copy.** This
is the defect eight earlier versions of this recipe shared without noticing.
@@ -288,7 +300,10 @@ This runs in the foreground and stops when you log out, so it is a first-start
check rather than a deployment. Section 4 needs the node reachable while you
type into a shell: use a second terminal, or supervise it. The unit file is in
[Operations](../../landing/docs/operations.html); this page deliberately does
-not carry a second copy of it to drift out of date.
+not carry a second copy of it to drift out of date. Point its `ExecStart` at
+`/opt/xerj/bin/xerj`, which is where the block above installs — that unit is
+written for the one-line installer's `/usr/local/bin/xerj`, and a unit copied
+across unedited fails to start.
Keep the listener on loopback. A network-facing listener requires the separate
production TLS/auth procedure; this recipe does not teach a cleartext opt-out.
diff --git a/landing/docs/recipes/air-gapped-deployment.html b/landing/docs/recipes/air-gapped-deployment.html
index 8c84e8e25..b6ce55040 100644
--- a/landing/docs/recipes/air-gapped-deployment.html
+++ b/landing/docs/recipes/air-gapped-deployment.html
@@ -104,12 +104,12 @@
&lt; &lt;(tr -d '\r' &lt; "$ASSET.sha256")
tar -xzf "$ASSET"
+ trap 'rm -rf "$OUT/release/$STAGE"' EXIT
test -x "$STAGE/xerj"
"$STAGE/xerj" --version
- rm -rf "$STAGE"
echo "staged $ASSET ($want) in $OUT"
)</pre>
- <p>The checksum proves archive integrity against the digest published beside it in the same release; it is not a signature, provenance statement, or attestation. <code class="inline">"$STAGE/xerj" --version</code> executes the staged binary, so the staging host must match the target platform; drop that line or change <code class="inline">TARGET</code> otherwise. The extracted tree is removed so that only the archive and its <code class="inline">.sha256</code> cross the airgap.</p>
+ <p>The checksum proves archive integrity against the digest published beside it in the same release; it is not a signature, provenance statement, or attestation. <code class="inline">"$STAGE/xerj" --version</code> executes the staged binary, so the staging host must match the target platform; drop that line, or stage a different target by changing <code class="inline">TARGET</code> here <strong>and</strong> the triple spelled out in the enclave block below. The extracted tree is removed by the <code class="inline">trap</code> on every exit path, including those failures, so that only the archive and its <code class="inline">.sha256</code> cross the airgap.</p>
<p><strong>Transfer <code class="inline">$OUT</code> itself and land it in the enclave at <code class="inline">/opt/xerj-staging</code></strong>, so the archive sits at <code class="inline">/opt/xerj-staging/release/</code> &mdash; the fixed path the enclave blocks read. Then set the same approved <code class="inline">TAG</code> and verify before extracting:</p>
<pre class="code">(
set -eu
@@ -163,7 +163,7 @@ mode = "lexical"
default_endpoint = ""
default_model = ""</pre>
<pre class="code">sudo -u xerj /opt/xerj/bin/xerj --config /etc/xerj/xerj.toml</pre>
- <p>Start it as <code class="inline">xerj</code>. On first start the authenticated admin key is written to <code class="inline">/var/lib/xerj/admin.key</code>. Keep the listener on loopback; a network-facing listener needs the production TLS/auth procedure. This command runs in the foreground and stops at logout, so it is a first-start check rather than a deployment &mdash; section 4 needs the node reachable from a shell, so use a second terminal or the unit file in <a href="/docs/operations.html">Operations</a>.</p>
+ <p>Start it as <code class="inline">xerj</code>. On first start the authenticated admin key is written to <code class="inline">/var/lib/xerj/admin.key</code>. Keep the listener on loopback; a network-facing listener needs the production TLS/auth procedure. This command runs in the foreground and stops at logout, so it is a first-start check rather than a deployment &mdash; section 4 needs the node reachable from a shell, so use a second terminal or the unit file in <a href="/docs/operations.html">Operations</a> &mdash; pointing its <code class="inline">ExecStart</code> at <code class="inline">/opt/xerj/bin/xerj</code>, where the block above installs, since that unit is written for the one-line installer's <code class="inline">/usr/local/bin/xerj</code>.</p>
<h2>3. Optional neural model</h2>
<p>Only when neural semantics are needed, stage the three loader files on the connected machine:</p>
diff --git a/landing/llms-full.txt b/landing/llms-full.txt
index c7318e7ee..3be13564e 100644
--- a/landing/llms-full.txt
+++ b/landing/llms-full.txt
@@ -141,7 +141,7 @@ Content types:
air-gapped or policy-constrained hosts, pre-download them and set
`embedding.local_model_dir`; nothing is then fetched.
-For a complete disconnected deployment procedure, including current GitHub release asset names, per-archive `.sha256` verification, model staging, loopback/API-key defaults, persisted WAL-tap overlays, and the exact limits of the procedure, use the [air-gapped deployment recipe](https://xerj.org/docs/recipes/air-gapped-deployment.html). The running binary has no runtime telemetry, update check, or license activation call. The Console's HTML has three external Google Fonts link elements (two preconnects and one stylesheet; stylesheet may fetch additional font files) and may attempt them before falling back to system fonts; this is not a claim of zero browser egress attempts. Release `.sha256` files provide integrity only, not signing or attestation.
+For a complete disconnected deployment procedure, including current GitHub release asset names, per-archive `.sha256` verification, model staging, loopback/API-key defaults, persisted WAL-tap overlays, and the exact limits of the procedure, use the [air-gapped deployment recipe](https://xerj.org/docs/recipes/air-gapped-deployment.html). The running binary has no runtime telemetry, update check, or license activation call. The Console's HTML is three embedded documents (`index.html`, `login.html`, `setup.html`, served under `/_xerj-console/`), each carrying the same three external Google Fonts link elements (two preconnects and one stylesheet; stylesheet may fetch additional font files) — nine in total — and may attempt them before falling back to system fonts; this is not a claim of zero browser egress attempts. Release `.sha256` files provide integrity only, not signing or attestation.
- Scroll is a BOUNDED SNAPSHOT, not a cursor — the ceiling is
<!-- generated:scroll-snapshot-cap -->10,000<!-- /generated:scroll-snapshot-cap --> documents.
diff --git a/landing/llms.txt b/landing/llms.txt
index 9c15fab0c..0d816bedb 100644
--- a/landing/llms.txt
+++ b/landing/llms.txt
@@ -129,7 +129,7 @@ install -m 755 xerj-*/xerj ~/.local/bin/xerj
`<target>` is `{x86_64,aarch64}-{unknown-linux-musl,unknown-linux-gnu,apple-darwin,pc-windows-msvc}` — e.g. `xerj-1.0.0-rc.16-x86_64-unknown-linux-musl.tar.gz`. Resolve `<tag>` from `https://api.github.com/repos/xerj-org/xerj/releases/latest`. Note what the checksum does and does not prove: it verifies the archive against the digest published beside it in the same release — integrity, not independent provenance.
-**Air-gapped deployment:** see the [air-gapped deployment recipe](https://xerj.org/docs/recipes/air-gapped-deployment.html) for exact release staging, checksum verification, optional local neural files, and the secure loopback/auth boundary. Lexical mode is offline by default; neural mode needs `config.json`, `tokenizer.json`, and `model.safetensors` staged locally. The running binary has no runtime telemetry, update check, or license activation call. The Console has three external Google Fonts link elements (two preconnects and one stylesheet; stylesheet may fetch additional font files) and may attempt them in a browser before falling back to system fonts.
+**Air-gapped deployment:** see the [air-gapped deployment recipe](https://xerj.org/docs/recipes/air-gapped-deployment.html) for exact release staging, checksum verification, optional local neural files, and the secure loopback/auth boundary. Lexical mode is offline by default; neural mode needs `config.json`, `tokenizer.json`, and `model.safetensors` staged locally. The running binary has no runtime telemetry, update check, or license activation call. The Console is three embedded documents (`index.html`, `login.html`, `setup.html`, served under `/_xerj-console/`), each carrying the same three external Google Fonts link elements (two preconnects and one stylesheet; stylesheet may fetch additional font files) — nine in total — and may attempt them in a browser before falling back to system fonts.
**If you cannot execute commands at all** (no shell, MCP/function-calling only), hand your operator this block and take over afterwards over HTTP: