docs: route role onboarding through decdn_chain; whoami and IPv4-only notes - #77
Merged
Merged
Conversation
… notes The decdn_node role README still showed bare `decdn setup` / `node bond` / `node register`, which fail on a role-deployed node with "rpc_url not set": on-chain CLI commands resolve rpc_url only from --rpc-url or blockchain.rpc_url, and the role keeps the URL in /etc/decdn/decdn.env. Use the decdn_chain helper from docs/lifecycle.md there, and state the argv-exposure tradeoff it carries. - lifecycle.md: name the upstream fix (env = "DECDN_RPC_URL" on CommonChainArgs.rpc_url), add a whoami command for the wallet address (keystore.json has no plaintext address), and say to register /ip4/ only. - requirements.md: the QUIC listener binds 0.0.0.0:4433, so "IPv6: supported" was misleading for the node itself. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
The role README currently uses an inline code span that contains a newline, which can render incorrectly on GitHub and should be reformatted for reliable documentation display.
Get a fresh assessment by requesting another Copilot review.
Review effort: Lite
Findings: 1
What changed in this PR
This PR updates operator documentation to ensure on-chain onboarding commands work with the current decdn CLI behavior by routing RPC URL usage through the decdn_chain helper, and clarifies network constraints (IPv4-only QUIC binding) plus a whoami workflow for obtaining the funding address.
Changes:
- Update onboarding examples to use
decdn_chainso--rpc-urlis correctly supplied from/etc/decdn/decdn.env. - Expand lifecycle guidance with an upstream fix note (
env = "DECDN_RPC_URL"), an/ip4/-only registration note, and awhoamicommand to print the wallet address. - Clarify requirements to state the node requires a public IPv4 address due to IPv4-only QUIC listening.
| File | Description |
|---|---|
| docs/requirements.md | Clarifies that QUIC is IPv4-only and the node needs a public IPv4 for /ip4/ multiaddr registration. |
| docs/lifecycle.md | Documents decdn_chain rationale, upstream DECDN_RPC_URL env fix, /ip4/-only registration, and adds whoami command guidance. |
| ansible/roles/decdn_node/README.md | Routes on-chain onboarding examples through decdn_chain and adds notes about /ip4/ multiaddrs and whoami. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
decdn/decdn#2144 (869141e9) binds QUIC on [::]:bind_port as well as 0.0.0.0:bind_port, falling back to IPv4-only (with a warn) on hosts without IPv6. The IPv4-only wording this PR added is now stale for new builds: - docs/lifecycle.md: register the /ip6/ multiaddr too on dual-stack hosts, check `ss -ulpn` shows [::]:4433 first, keep /ip4/-only for older builds, and add it after an upgrade with update-multiaddrs passing both addresses (it replaces the on-chain set). - docs/requirements.md: IPv6 is supported alongside IPv4 since #2144. - roles/decdn_node/README.md: same, next to the register example. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.
Summary
decdn setupfailed on a real node withError: rpc_url not set (pass --rpc-url or set blockchain.rpc_url). The on-chain CLI commands resolverpc_urlonly from--rpc-urlor fromblockchain.rpc_urlin node.toml (decdn/crates/cli/src/commands/chain_ctx.rs).CommonChainArgs.rpc_urlhas noenv =. The role writes the URL to/etc/decdn/decdn.env, so loading that file withEnvironmentFile=has no effect on these commands.Already on
main: #69 removedansible/docs/launch-runbook.md, which had the broken command.docs/lifecycle.md§ Running on-chain commands now has adecdn_chainhelper using the working form (/bin/sh -c 'exec decdn … --rpc-url "$DECDN_RPC_URL"') and notes thepsexposure. This PR fixes what's left:ansible/roles/decdn_node/README.md§ On-chain onboarding: the examples still calleddecdn setup/node bond/node registerdirectly. They now go throughdecdn_chain. The section also says the URL shows up in argv while the command runs.docs/lifecycle.md:env = "DECDN_RPC_URL"toCommonChainArgs.rpc_url. ThenEnvironmentFile=alone is enough and the URL stays out of argv.whoamicommand, run asdecdn, that prints the wallet address to fund.keystore.jsonhas no plaintext address field.whoamitakes no--rpc-url, so it doesn't go through the helper./ip4/, plus/ip6/on dual-stack hosts running a build with fix(node): bind IPv6 on the configured QUIC port decdn#2144 (869141e9), which binds QUIC on[::]:4433too. Older builds stay/ip4/-only. To add/ip6/after an upgrade, useupdate-multiaddrswith both addresses (it replaces the on-chain set). Same note in the role README.docs/requirements.md: the IPv6 line now says when it applies. Since fix(node): bind IPv6 on the configured QUIC port decdn#2144 the listener binds both0.0.0.0:4433and[::]:4433, and it falls back to IPv4-only on hosts without IPv6. Older builds bind IPv6 on a random port, so they are IPv4-only on 4433. (An earlier revision of this PR said IPv4-only unconditionally. #2144 merged in the meantime.)Docs only.
sudostays generic (sudo-rs hosts may needsudo.wsforsystemd-run --pty).Test plan
markdownlint-cli2clean on the changed filessystemd-run … /bin/sh -c 'exec decdn … --rpc-url "$DECDN_RPC_URL" …' --dry-runform was confirmed on a real Ubuntu 26.04 node, per the issue report🤖 Generated with Claude Code