Skip to content

docs: gateway operator updates for Release 85 - #187

Merged
vilenarios merged 11 commits into
mainfrom
docs/r85-operator-updates
Oct 17, 2026
Merged

docs: gateway operator updates for Release 85#187
vilenarios merged 11 commits into
mainfrom
docs/r85-operator-updates

Conversation

@vilenarios

@vilenarios vilenarios commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

Brings docs.ar.io up to date with ar-io-node Release 85. Merge once Release 85 is released. The pages say "Release 85 or later" and describe features that ship in it, including ar-io/ar-io-node#1032, #1033 and #1034.

Every gap was first confirmed against the gateway's code, and every fact here is sourced from ar-io-node's own docs or code.

Index Sharing

  • Tracker: peers announce through the gateway's HTTPS at /ar-io/indexes/announce, which Envoy forwards to the sidecar on 6970. Publishers no longer open 6969 unless peers announce to it directly.
    • The Ports table, the setup flags (--public-url), the fleet steps and the NGINX note are all updated.
    • A callout says to upgrade the Envoy image with core: an older Envoy answers 404 and every announce fails without an error.
    • New env rows: INDEX_SWARM_TRACKER_PROXY_*.
  • Feeds and WebSeed:
    • The RSS feed of each index's torrents, /ar-io/info indexes.feeds, and following a publisher in qBittorrent;
    • the WebSeed a served .torrent names, and INDEXES_TORRENT_WEBSEED;
    • an env row for INDEXES_PUBLIC_URL.
  • L1 bands: --l1 and L1_BAND_IMPORT_ENABLED fill a gateway's L1 history while it runs; a new gateway follows the chain tip from the start. The stopped import is the fast path for a new core.db only. Quick start points at it.

Observer and chunks

  • Troubleshooting covers the offset (chunk-proof) checks:
    • what they test, and that they fail gateways by default;
    • failureCategory;
    • the fixes: upgrade core, test /chunk/<offset>, warm-up after a restart, and remove tip-5.
  • There are three pass/fail tests, and each observer takes a 2-of-3 majority.
  • New env rows: OFFSET_*, ARWEAVE_PEER_CHUNK_GET_MAX_PEER_ATTEMPT_COUNT, PREFERRED_CHUNK_*_NODE_URLS.
  • An OBSERVER_IMAGE_TAG pinned in .env overrides the new compose default.

Other

  • Upgrading gains "Release-specific steps" for Release 85:
    • upgrade Envoy with core;
    • keep the same -f files and --profile flags;
    • update a pinned observer tag;
    • purge cached gzip bodies;
    • don't trust gateways older than the gzip fix.
  • A new page for the ar-io-node CLI.
  • ClickHouse: with CLICKHOUSE_IMPORT_SKIP_UNCHANGED (the default), an unchanged re-import no longer reapplies TTL rules. Also added CLICKHOUSE_AUTO_IMPORT_DEBUG_RETRY_WINDOW_S, and corrected CLICKHOUSE_AUTO_IMPORT_HEIGHT_INTERVAL from 1000 to 10000.
  • Troubleshooting: removed two AO-era entries whose errors and settings no longer exist, and fixed the reference-gateway note.
  • CDB64: /ar-io/offsets answers from local CDB64.
  • Content moderation: a blocked sandbox root answers 451 (404 otherwise).
  • Env page: links the full list of environment variables.
  • 46 "Release 85, not released yet" callouts now read "Release 85 or later".

Checks: npm run check-links reports 0 errors; npm run lint and npm run build pass, the build with the same warnings as main.

Left as is: the torrent magnet examples still show :6969 tracker URLs, as they were when written. I couldn't confirm turbo's current tracker list.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VtHwB55wzxPvWPD64D3pEx

vilenarios and others added 10 commits October 12, 2026 03:27
@vilenarios @claude
docs(index-sharing): announce to the tracker through the gateway's HTTPS
3ef06c2 
From Release 85, peers announce to a publisher's tracker at
https://<gateway>/ar-io/indexes/announce, and Envoy forwards it to the
sidecar's second listener on 6970. Port 6969 needs opening only for
direct announces. Document the --public-url flag, the new tracker proxy
settings, the Envoy upgrade it needs, and the fleet pin to Envoy :3000.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VtHwB55wzxPvWPD64D3pEx
@vilenarios @claude
docs(troubleshooting): offset checks, chunk fixes and AO-era entries
3dc5297 
Observers on the Release 85 image check that a sampled share of gateways
serve /chunk/<offset> with a valid proof, and fail them by default. Say
what the check is, list its failureCategory values, and how to fix a
failure. Document the three pass/fail tests and the 2-of-3 majority, the
new chunk and offset settings, and the OBSERVER_IMAGE_TAG pin. Remove the
AO-era network contract and CU entries, and name the observer's real
reference gateways.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VtHwB55wzxPvWPD64D3pEx
@vilenarios @claude
docs(l1): fill L1 history from bands while the gateway runs
b3f60c8 
Release 85 fills a gateway's L1 history from installed parquet-l1 bands
while it runs (L1_BAND_IMPORT_ENABLED, index-l1-import --fill), and
index-swarm-setup --subscribe <wallet> --l1 sets it up. Make that the
main path. The stopped import is now only the fast path for a new
core.db, since it refuses one a gateway has run on. Add the four
L1_BAND_IMPORT_* settings and a pointer from the quick start.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VtHwB55wzxPvWPD64D3pEx
@vilenarios @claude
docs: say Release 85 or later instead of not released yet
b11ce99 
Release 85 ships, so word its requirement callouts as "requires
Release 85 or later" and drop the pre-release notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VtHwB55wzxPvWPD64D3pEx
@vilenarios @claude
docs(index-sharing): RSS feeds of index torrents and the served WebSeed
b3fac85 
Release 85 serves an RSS feed of each index's torrents at
/ar-io/indexes/feed/<index>.xml, listed in /ar-io/info indexes.feeds,
and names the gateway as a WebSeed in each served .torrent. Show how to
follow a publisher in qBittorrent, what the WebSeed costs a publisher and
how to turn it off, and add INDEXES_PUBLIC_URL and
INDEXES_TORRENT_WEBSEED.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VtHwB55wzxPvWPD64D3pEx
@vilenarios @claude
docs(clickhouse): TTL rules are not reapplied by an unchanged re-import
b1afd54 
With CLICKHOUSE_IMPORT_SKIP_UNCHANGED=true, the Release 85 default, a
re-import skips unchanged rows and does not refresh expires_at. Point to
the mutation the Parquet and ClickHouse guide describes instead. Add
CLICKHOUSE_IMPORT_SKIP_UNCHANGED and
CLICKHOUSE_AUTO_IMPORT_DEBUG_RETRY_WINDOW_S to the auto-import table,
and correct the height interval default to 10000.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VtHwB55wzxPvWPD64D3pEx
@vilenarios @claude
docs(upgrading): add the steps a Release 85 upgrade needs
f638098 
Upgrade Envoy with core for the tracker route, bring the sidecars up
with the same -f files and profiles so they move to the new core image,
update a pinned OBSERVER_IMAGE_TAG, purge gzip bodies an NGINX cache
stored before the fix, and stop trusting gateways older than #964.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VtHwB55wzxPvWPD64D3pEx
@vilenarios @claude
docs(gateway): add a page for the ar-io-node CLI
c0159d1 
Release 85 ships tools/ar-io-node, which runs in the core image and
prints one JSON value on stdout. Say what it is, list its commands in a
line each, and link the full reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VtHwB55wzxPvWPD64D3pEx
@vilenarios @claude
docs(gateway): offsets from local CDB64, sandbox root status, envs link
bce0151 
From Release 85, /ar-io/offsets also answers from CDB64 indexes on local
disk (offsets_lookup_total), and the bare root of a sandbox subdomain
answers 451 when blocked and 404 otherwise. Link the full list of
environment variables in the gateway repository.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VtHwB55wzxPvWPD64D3pEx
@vilenarios @claude
docs: tidy wording from a review of the Release 85 changes
16fc392 
Reflow a callout, drop a stray character from a diagram label, say that
the observer's 3 checks and 2-of-3 majority are defaults, and smooth the
gzip upgrade notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VtHwB55wzxPvWPD64D3pEx
@vilenarios
vilenarios requested a review from a team as a code owner October 12, 2026 03:49
@vilenarios @claude
docs: correct what an independent fact check of these changes found
b9ddc27 
Every claim was checked against the gateway's code. Fixed:

- The torrent engine runs qBittorrent's image, not the core image; only
  its setup step, the sidecar and index-export run core (index-export
  honours INDEX_EXPORT_IMAGE_TAG).
- The tracker origin is --public-url, then INDEXES_PUBLIC_URL, then
  ARNS_ROOT_HOST; the direct-port fallback needs a public host, uses
  INDEX_SWARM_TRACKER_PORT, and without one the script writes no tracker.
  An existing INDEX_SWARM_TRACKERS is kept, so Release 84 publishers get an
  upgrade step to move announces to the gateway route.
- The announce check now uses the setup script's own test (`?info_hash=x`
  answers a bencoded failure reason); a bare 503 is not success.
- On a new gateway, run setup without --restart before the first start;
  --restart would start core and the sidecar alone.
- Observer: `unverifiable` never counts as a pass (only an all-unverifiable
  check is inconclusive), and the report lists the best observation's
  samples.
- index-l1-verify proves the bands form one consistent chain; tying it to
  the chain needs --anchor-from, and replaced folders must go first.
- The publication doesn't sign a .torrent; a gateway with HTTPSIG signs
  its response. qBittorrent's queue defaults were not provable; dropped.
- CLICKHOUSE_AUTO_IMPORT_MAX_ROWS_PER_FILE defaults to 1000000.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VtHwB55wzxPvWPD64D3pEx
@vilenarios vilenarios mentioned this pull request Oct 16, 2026
Merged
@vilenarios
vilenarios merged commit 1007f12 into main Oct 17, 2026
@vilenarios
vilenarios deleted the docs/r85-operator-updates branch October 17, 2026 16:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@vilenarios