docs: prune and de-drift deployment and production docs - #605
Merged
Conversation
Trim the deployment and production corpus to the current contract and fix ownership: docs/deployment.md owns the engine.toml reference, module artefact builds, and local runs; docs/production.md owns the production deploy (systemd, backup, observability wiring); docs/deployment/docker.md owns containers; docs/deployment/multi-chain.md owns multi-chain config; docs/06-production-hardening.md owns the hardening design facts and stops restating deploy steps. Each of the others links the owner rather than repeating. Verify every config key, default, metric name, port, and binary against the code on dev/m1: the production binary is shepherd (not nexum-cli), resource caps live under [limits] (not [engine.limits]), the redb file is local-store.redb, the metric prefix is shepherd_* with the eleven-metric surface the runtime actually emits, and the orderbook URL override is the cow-venue adapter's own [config] orderbook-url rather than an engine-side extensions.cow table. Drop the fabricated cli subcommands, epoch mechanism, health endpoint, and nexum_* metric table. Purge em dashes and repo-name and planning drift.
mfw78
force-pushed
the
docs/598-deploy-production
branch
from
July 25, 2026 03:18
53fd04f to
1fdb681
Compare
Hard-wrapped prose churns diffs: a one-word edit reflows the whole paragraph. Join each paragraph onto a single logical line and let it soft-wrap. Content unchanged (word and heading counts preserved); code fences, tables, lists, blockquotes and headings untouched.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Prune and de-drift the deployment and production documentation set (README, docs/deployment.md, docs/production.md, docs/deployment/docker.md, docs/deployment/multi-chain.md, docs/06-production-hardening.md), cutting it from ~2020 to ~710 lines.
Fix ownership so each topic has one owner: docs/deployment.md owns the engine.toml reference, module artefact builds, and local runs; docs/production.md owns the production deploy procedure (systemd, backup, observability wiring); docs/deployment/docker.md owns containers; docs/deployment/multi-chain.md owns multi-chain config; docs/06-production-hardening.md owns the hardening design facts and stops restating deploy steps. The others link the owner by name instead of duplicating config, metric, and procedure tables.
Why
The docs had drifted off the current dev/m1 architecture and were thick with planning prose, aspirational 0.3/M-number scheduling, and fabricated interfaces. Verified against the code in this tree and corrected:
shepherd(registers the venue platform and the Prometheus add-on), notnexum/-p nexum-cli; the barenexumbinds no metrics exporter and cannot load the cow adapter.[limits](and[limits.http|chain|logs|poison|dispatch]), not[engine.limits]; defaults confirmed (fuel 1e9, event_deadline_secs 120, memory 64 MiB, state 50 MiB).local-store.redb(was variouslyls.redb/state.redb).shepherd_*with the eleven metrics the runtime actually emits; dropped the fabricatednexum_*table and the non-existentshepherd_cow_api_submit_total/shepherd_fuel_consumed/shepherd_memory_peak_bytes/shepherd_module_uptime_seconds.videre:venueadapter contract: the orderbook URL override is the cow-venue adapter's ownmodule.toml[config] orderbook-url, not an engine-side[extensions.cow.orderbook_urls]/ cow-api backend (which no longer exists). Adapters are wired via[[adapters]].[limits.poison]), not 10; restart backoff caps at 300s.nexum module list/restart/reload,nexum state purge/compact,nexum health), the--check-integrity-only/--log-format jsonflags, the epoch-interruption mechanism (the real backstop is a per-dispatch tokio timeout), and the:8080/healthfuture-direction endpoint.bleu/nullis-shepherdrepo/image names (CI publishesghcr.io/nullislabs/shepherd).Testing
Documentation-only, pure Markdown: no build. Confirmed no internal links point at a deleted or renamed file (none were deleted or renamed), zero em dashes remain, and every config key, default, metric name, port, and binary name was checked against dev/m1 source.
AI Assistance
Documentation-only sweep; verified against dev/m1 source, no build run (Markdown only).
Deviations flagged
docker-compose.yml(outside this doc set's edit scope): the default imageghcr.io/bleu/nullis-shepherd:latestdoes not match the CI-publishedghcr.io/nullislabs/shepherd(the workflow uses${{ github.repository }}), so a freshdocker compose pullfetches a stale or absent image. The docs now document the correct name; the compose default still needs a fix.require_ws = falsechain key and claimed the engine logs a boot-time ERROR for an HTTP RPC URL under a subscription. Neither exists:ChainConfig(engine_config.rs) has no such field, andprovider_pool.rsopens HTTP transports that polleth_getBlockByNumber/eth_getLogswith no boot error. Corrected in-doc to state HTTP is fully supported.[[chains.endpoints]]withpriority,[chains.rpc_policy],nexum_rpc_fallbacks_total).ChainConfigcarries a singlerpc_urlandProviderPooldoes no failover; resilience is aRetryBackoffLayerplus a per-request timeout only. Corrected in-doc to the single-endpoint model.Part of #598.