Document the --enable-core-manual-close flag in Quickstart advanced usage - #2850
Conversation
…sage Adds a Manual close mode section to Operation Modes covering the flag, its default value, the MANUAL_CLOSE core setting it controls, and the manualclose trigger, and adds a run-command example that starts a local network with the flag enabled. Fixes #2772
There was a problem hiding this comment.
Pull request overview
Documents Quickstart’s manual ledger-close mode and adds platform-specific usage examples.
Changes:
- Documents the flag, configuration, endpoint, and one-ledger behavior.
- Adds macOS/Linux and Windows run commands.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Summary |
|---|---|
docs/tools/quickstart/advanced-usage/run-command-examples.mdx |
Adds platform-specific manual-close startup examples. |
docs/tools/quickstart/advanced-usage/operation-modes.mdx |
Documents manual close mode and its configuration. |
Suppressed comments (1)
docs/tools/quickstart/advanced-usage/run-command-examples.mdx:127
- This command only publishes port 8000, but the documented
curl http://localhost:11626/manualcloseuses stellar-core's HTTP port. As shown, the host cannot reach port 11626, so manual close fails; publish the core port as well.
-p "8000:8000" `
Note
Copilot is running an experiment and ran this review at Lite.
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The manual close examples instruct users to curl http://localhost:11626/manualclose, but the container only published port 8000, so the host could not reach stellar-core's HTTP endpoint. Also publish 11626 in both the macOS/Linux and Windows commands.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
Suppressed comments (2)
Previously missed (1) — in code that hasn't changed since the last review.
docs/tools/quickstart/advanced-usage/operation-modes.mdx:56
- Qualify this as the behavior when no parameters are supplied. Current Stellar Core accepts a
ledgerSeqparameter formanualclosewhenRUN_STANDALONE=true(as in a local network), and that parameter can target a later ledger sequence, so the absolute claim that every invocation advances exactly one is inaccurate. Issue 4040 specifically requests acountparameter for closing multiple consecutive ledgers.
docs/tools/quickstart/advanced-usage/run-command-examples.mdx:129
- Bind port 11626 to loopback here as well. As written, Docker publishes Stellar Core's unauthenticated administrative HTTP interface on all host interfaces; this conflicts with the warning in
docs/validators/admin-guide/prerequisites.mdx:54-62and unnecessarily exposes commands such asmanualcloseto the local network.
-p "11626:11626" `
Publish port 11626 on 127.0.0.1 so stellar-core's unauthenticated admin endpoint is not exposed on all host interfaces, matching the warning in docs/validators/admin-guide/prerequisites.mdx. Also qualify the per-invocation advance claim: stellar-core accepts optional ledgerSeq and closeTime parameters on manualclose when RUN_STANDALONE=true, so exactly-one only holds without parameters.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (3)
docs/tools/quickstart/advanced-usage/operation-modes.mdx:48
- This wording makes the flag sound valid for every Quickstart network mode, but the current stellar-core startup check rejects
MANUAL_CLOSE=trueunlessNODE_IS_VALIDATORis set; Quickstart's testnet config does not set it. Please scope this instruction to--local(as the example below does) or document the validator prerequisite, otherwise copying the flag into a testnet command makes core exit instead of entering manual-close mode.
By default, ledgers close automatically every few seconds. For deterministic local testing, you can disable automatic closing by passing the `--enable-core-manual-close` flag when starting the container. The flag sets the `MANUAL_CLOSE` setting in the container's generated `etc/stellar-core.cfg`, and defaults to `false` when not specified.
docs/tools/quickstart/advanced-usage/operation-modes.mdx:56
ledgerSeqdoes not close every ledger up to the requested sequence. In standalone mode Core advances its header totarget - 1and then closes only the target ledger, so intermediate sequence numbers are skipped; the current wording overstates the behavior and weakens the one-ledger caveat. Describe this as selecting the sequence number of the ledger to close.
With no parameters, each `manualclose` invocation advances the ledger by one. On a standalone network, the command also accepts an optional `ledgerSeq` parameter to close up to a specific ledger sequence, and an optional `closeTime` parameter to set the close time of the next ledger. Support for closing multiple consecutive ledgers with a single `count` parameter is requested in [stellar-core issue 4040](https://github.com/stellar/stellar-core/issues/4040). For a complete example of starting a local network with the flag enabled, see [Run Commands](./run-command-examples.mdx).
docs/tools/quickstart/advanced-usage/operation-modes.mdx:48
- The flag substitution is only performed while initializing a new Core config: the Quickstart start script returns early for an already-initialized persistent volume, so adding this flag on a later
docker rundoes not changeetc/stellar-core.cfg. As written, this broad instruction can make persistent users believe the flag took effect; scope it to first initialization/ephemeral mode or explain that existing persistent configs must be edited or recreated.
By default, ledgers close automatically every few seconds. For deterministic local testing, you can disable automatic closing by passing the `--enable-core-manual-close` flag when starting the container. The flag sets the `MANUAL_CLOSE` setting in the container's generated `etc/stellar-core.cfg`, and defaults to `false` when not specified.
Note
Copilot is running an experiment and ran this review at Lite.
Quickstart only generates stellar-core.cfg on first initialization, so the flag has no effect on an already-initialized persistent volume; spell that out. Also correct the ledgerSeq description: stellar-core selects the sequence number of the ledger to close and skips intermediates rather than closing every ledger up to the target.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (1)
docs/tools/quickstart/advanced-usage/operation-modes.mdx:56
- The
ledgerSeqandcloseTimeparameters are accepted by stellar-core only whenRUN_STANDALONE=true, but the--localQuickstart configuration used by the new example does not set that option. As written, readers may try these parameters against the documented command and get a rejection; please state theRUN_STANDALONErequirement and that this example does not enable it, or remove the parameter details.
With no parameters, each `manualclose` invocation advances the ledger by one. On a standalone network, the command also accepts an optional `ledgerSeq` parameter that selects the sequence number of the ledger to close (intermediate ledgers are skipped), and an optional `closeTime` parameter to set the close time of the next ledger. Support for closing multiple consecutive ledgers with a single `count` parameter is requested in [stellar-core issue 4040](https://github.com/stellar/stellar-core/issues/4040). For a complete example of starting a local network with the flag enabled, see [Run Commands](./run-command-examples.mdx).
Note
Copilot is running an experiment and ran this review at Lite.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
Suppressed comments (3)
Previously missed (1) — in code that hasn't changed since the last review.
docs/tools/quickstart/advanced-usage/operation-modes.mdx:56
- The
--localconfiguration used by the example does not set stellar-core'sRUN_STANDALONE=true; current core acceptsledgerSeqandcloseTimeonly when that setting is enabled, otherwise the request is rejected. Please name theRUN_STANDALONE=truerequirement and clarify that these parameters are not available with the Quickstart command shown above, so readers do not try them against this example.
docs/tools/quickstart/advanced-usage/operation-modes.mdx:48
- This cadence conflicts with the Quickstart network description at
docs/tools/quickstart/network-modes.mdx:47, which says the local network closes a ledger every one second. Since this section introduces the flag for--local, describe the default as once per second rather than "every few seconds."
By default, ledgers close automatically every few seconds. For deterministic local testing, you can disable automatic closing by passing the `--enable-core-manual-close` flag when starting the container. The flag sets the `MANUAL_CLOSE` setting in the `etc/stellar-core.cfg` file that the container generates when it initializes, and defaults to `false` when not specified. It applies to the `--local` network: stellar-core refuses to start with `MANUAL_CLOSE` enabled unless `NODE_IS_VALIDATOR` is set, and the Quickstart local network configuration is the one that sets it. The configuration is only generated on first initialization, so adding the flag to a container that already has one (for example, on a persistent volume) has no effect until the configuration is regenerated.
docs/tools/quickstart/advanced-usage/operation-modes.mdx:48
stellar-coredoes not refuse to start merely becauseMANUAL_CLOSE=trueandNODE_IS_VALIDATOR=false; the current implementation checksNODE_IS_VALIDATORwhenmanualcloseis invoked. This wording can mislead users about startup behavior and hides that a non-validator node instead fails when the endpoint is called. Please describe the requirement at invocation time.
By default, ledgers close automatically every few seconds. For deterministic local testing, you can disable automatic closing by passing the `--enable-core-manual-close` flag when starting the container. The flag sets the `MANUAL_CLOSE` setting in the `etc/stellar-core.cfg` file that the container generates when it initializes, and defaults to `false` when not specified. It applies to the `--local` network: stellar-core refuses to start with `MANUAL_CLOSE` enabled unless `NODE_IS_VALIDATOR` is set, and the Quickstart local network configuration is the one that sets it. The configuration is only generated on first initialization, so adding the flag to a container that already has one (for example, on a persistent volume) has no effect until the configuration is regenerated.
Note
Copilot is running an experiment and ran this review at Lite.
ElliotFriend
left a comment
ElliotFriend
left a comment
There was a problem hiding this comment.
Thanks for picking this up, and nice work tracking the flag down in the start script.
Two factual corrections inline, both in the new manual close section. The short version: the NODE_IS_VALIDATOR check fires when you call manualclose, not at startup, and the ledgerSeq/closeTime parameters require RUN_STANDALONE=true, which Quickstart never sets on any network.
One of the suggestions also drops the stellar-core#4040 link. Nothing seems to be moving on that issue, and pointing at it reads as a promise. The one-ledger limit still gets stated plainly, which was the substantive part of the ask in #2772.
Everything else looks good. The loopback bind on 11626 is the right call, the tab structure matches the surrounding examples, and there's no existing manualclose coverage elsewhere in the repo to reconcile with.
One follow-up for a separate PR, not this one: the ## Local section in network-modes.mdx lists the local-only parameters (--protocol-version and --limits), and this flag belongs there too with a link across.
|
|
||
| ## Manual close mode | ||
|
|
||
| By default, ledgers close automatically every few seconds. For deterministic local testing, you can disable automatic closing by passing the `--enable-core-manual-close` flag when starting the container. The flag sets the `MANUAL_CLOSE` setting in the `etc/stellar-core.cfg` file that the container generates when it initializes, and defaults to `false` when not specified. It applies to the `--local` network: stellar-core refuses to start with `MANUAL_CLOSE` enabled unless `NODE_IS_VALIDATOR` is set, and the Quickstart local network configuration is the one that sets it. The configuration is only generated on first initialization, so adding the flag to a container that already has one (for example, on a persistent volume) has no effect until the configuration is regenerated. |
There was a problem hiding this comment.
Two corrections here:
Core doesn't refuse to start. The NODE_IS_VALIDATOR check is in ApplicationImpl::manualClose, not startup validation, so a --testnet --enable-core-manual-close container starts fine and only fails when you hit the endpoint.
The flag isn't scoped to --local. MANUAL_CLOSE=__MANUAL_CLOSE__ is in all four config templates. Local is the only usable one because local/core/etc/stellar-core.cfg:12 is the only config setting NODE_IS_VALIDATOR=true.
Suggestion below also splits the paragraph, moves the persistent-volume caveat into a note, and fixes the cadence (network-modes.mdx says local closes every one second, not "every few seconds").
| By default, ledgers close automatically every few seconds. For deterministic local testing, you can disable automatic closing by passing the `--enable-core-manual-close` flag when starting the container. The flag sets the `MANUAL_CLOSE` setting in the `etc/stellar-core.cfg` file that the container generates when it initializes, and defaults to `false` when not specified. It applies to the `--local` network: stellar-core refuses to start with `MANUAL_CLOSE` enabled unless `NODE_IS_VALIDATOR` is set, and the Quickstart local network configuration is the one that sets it. The configuration is only generated on first initialization, so adding the flag to a container that already has one (for example, on a persistent volume) has no effect until the configuration is regenerated. | |
| By default, ledgers close automatically. (In local network mode, that's once every second.) For deterministic local testing, you can disable automatic closing by passing the `--enable-core-manual-close` flag when starting the container. The flag sets the `MANUAL_CLOSE` setting in the `etc/stellar-core.cfg` file that the container generates when it initializes, and defaults to `false` when not specified. | |
| Manual close is only usable in local network mode. Stellar Core requires `NODE_IS_VALIDATOR=true` to service a manual close request, and the local network is the only Quickstart configuration that sets it. The flag is accepted on the other networks and the container will start normally, but the `manualclose` request itself will fail. | |
| :::note | |
| The core configuration is only generated the first time a container initializes. Adding this flag to a container that already has a configuration (on a persistent volume, for example) has no effect. To pick up the change, start a fresh ephemeral container or clear the mounted volume. | |
| ::: |
| curl "http://localhost:11626/manualclose" | ||
| ``` | ||
|
|
||
| With no parameters, each `manualclose` invocation advances the ledger by one. On a standalone network, the command also accepts an optional `ledgerSeq` parameter that selects the sequence number of the ledger to close (intermediate ledgers are skipped), and an optional `closeTime` parameter to set the close time of the next ledger. Support for closing multiple consecutive ledgers with a single `count` parameter is requested in [stellar-core issue 4040](https://github.com/stellar/stellar-core/issues/4040). For a complete example of starting a local network with the flag enabled, see [Run Commands](./run-command-examples.mdx). |
There was a problem hiding this comment.
These parameters aren't reachable from Quickstart at all. CommandHandler::manualClose rejects any parameter unless RUN_STANDALONE=true, and RUN_STANDALONE appears nowhere in the quickstart repo, so Core's default of false always applies. --enable-core-manual-close doesn't change that; the two settings are independent.
"On a standalone network" makes it worse, since network-modes.mdx tells readers the local passphrase is literally Standalone Network ; February 2017.
Also dropping the stellar-core#4040 link, since nothing's moving on it and a stalled issue reads as a promise. The one-ledger limit is the part readers need.
(Your "intermediate ledgers are skipped" wording is correct, just not reachable here.)
| With no parameters, each `manualclose` invocation advances the ledger by one. On a standalone network, the command also accepts an optional `ledgerSeq` parameter that selects the sequence number of the ledger to close (intermediate ledgers are skipped), and an optional `closeTime` parameter to set the close time of the next ledger. Support for closing multiple consecutive ledgers with a single `count` parameter is requested in [stellar-core issue 4040](https://github.com/stellar/stellar-core/issues/4040). For a complete example of starting a local network with the flag enabled, see [Run Commands](./run-command-examples.mdx). | |
| Each `manualclose` invocation advances the ledger by one. For a complete example of starting a local network with the flag enabled, see [Run Commands](./run-command-examples.mdx). |
|
Both corrections applied, thanks for the detail on where the The manual close section now says the flag is accepted on every network but only usable on local, the persistent-volume caveat is in a note, and the cadence is one second. The unreachable Happy to open the |
ElliotFriend
left a comment
ElliotFriend
left a comment
There was a problem hiding this comment.
lgtm! thanks for getting this fixed up!
|
PR Preview: torn down |
|
Your two corrections were the useful part of this review, @ElliotFriend: the The same pass caught Dropping the stellar-core#4040 link was the right call too, since a stalled issue reads as a promise rather than a limitation. Thanks for the careful read. |
Fixes #2772
The Quickstart container supports manual ledger close via
--enable-core-manual-close, but no Quickstart page named the flag. This adds it to the advanced usage section:false, theMANUAL_CLOSEsetting it writes intoetc/stellar-core.cfg, and how a close is triggered via themanualclosecommand on stellar-core's HTTP endpoint (port11626).manualcloseinvocation advances exactly one ledger, linking stellar-core#4040 where support for closing N ledgers is requested, so the docs do not imply a count parameter exists.Flag behavior was verified against the
startscript on the currentstellar/quickstartmain: the flag is boolean, defaults tofalse(ENABLE_CORE_MANUAL_CLOSE), and replaces__MANUAL_CLOSE__in the generated core config.