From 1367f1c7c463f5762025c88c85e3057435f721cd Mon Sep 17 00:00:00 2001 From: devtechedge Date: Sat, 12 Sep 2026 01:09:42 +0530 Subject: [PATCH 1/6] Document the --enable-core-manual-close flag in Quickstart advanced usage 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 --- .../advanced-usage/operation-modes.mdx | 12 +++++++ .../advanced-usage/run-command-examples.mdx | 32 +++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/docs/tools/quickstart/advanced-usage/operation-modes.mdx b/docs/tools/quickstart/advanced-usage/operation-modes.mdx index a87779f84b..a0fa9a39ec 100644 --- a/docs/tools/quickstart/advanced-usage/operation-modes.mdx +++ b/docs/tools/quickstart/advanced-usage/operation-modes.mdx @@ -42,3 +42,15 @@ Upon launching a persistent mode container for the first time, the launch script 1. Run an interactive session of the container at first, ensuring that all services start and run correctly. 2. Shut down the interactive container (using Ctrl-C). 3. Start a new container using the same host directory in the background. + +## 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. + +With manual close enabled, ledgers only advance when you explicitly trigger a close by sending the `manualclose` command to stellar-core's HTTP endpoint on port `11626`: + +```sh +curl "http://localhost:11626/manualclose" +``` + +Each `manualclose` invocation advances the ledger by exactly one. Support for closing multiple ledgers per invocation 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). diff --git a/docs/tools/quickstart/advanced-usage/run-command-examples.mdx b/docs/tools/quickstart/advanced-usage/run-command-examples.mdx index 532a332fae..15daa7393a 100644 --- a/docs/tools/quickstart/advanced-usage/run-command-examples.mdx +++ b/docs/tools/quickstart/advanced-usage/run-command-examples.mdx @@ -102,3 +102,35 @@ docker run -it --rm ` + +Start an ephemeral local network with manual ledger close enabled. Ledgers only advance when you send the `manualclose` command to stellar-core's HTTP endpoint (see [Operation Modes](./operation-modes.mdx)): + + + + + +```sh +docker run -d \ + -p "8000:8000" \ + --name stellar \ + stellar/quickstart \ + --local \ + --enable-core-manual-close +``` + + + + + +```powershell +docker run -d ` + -p "8000:8000" ` + --name stellar ` + stellar/quickstart ` + --local ` + --enable-core-manual-close +``` + + + + From 3a8a81ab9b53efaf820091bbd8e88d07a993792b Mon Sep 17 00:00:00 2001 From: Devayan Mandal Date: Sat, 12 Sep 2026 02:40:20 +0530 Subject: [PATCH 2/6] Publish stellar-core HTTP port in manual close examples 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. --- docs/tools/quickstart/advanced-usage/run-command-examples.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/tools/quickstart/advanced-usage/run-command-examples.mdx b/docs/tools/quickstart/advanced-usage/run-command-examples.mdx index 15daa7393a..b018e09e94 100644 --- a/docs/tools/quickstart/advanced-usage/run-command-examples.mdx +++ b/docs/tools/quickstart/advanced-usage/run-command-examples.mdx @@ -112,6 +112,7 @@ Start an ephemeral local network with manual ledger close enabled. Ledgers only ```sh docker run -d \ -p "8000:8000" \ + -p "11626:11626" \ --name stellar \ stellar/quickstart \ --local \ @@ -125,6 +126,7 @@ docker run -d \ ```powershell docker run -d ` -p "8000:8000" ` + -p "11626:11626" ` --name stellar ` stellar/quickstart ` --local ` From 7459511cbebc09e407f880b7222c507d46f736ac Mon Sep 17 00:00:00 2001 From: devtechedge Date: Sat, 12 Sep 2026 02:53:45 +0530 Subject: [PATCH 3/6] Bind core HTTP port to loopback and qualify manualclose behavior 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. --- docs/tools/quickstart/advanced-usage/operation-modes.mdx | 2 +- docs/tools/quickstart/advanced-usage/run-command-examples.mdx | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tools/quickstart/advanced-usage/operation-modes.mdx b/docs/tools/quickstart/advanced-usage/operation-modes.mdx index a0fa9a39ec..1b0d281ae6 100644 --- a/docs/tools/quickstart/advanced-usage/operation-modes.mdx +++ b/docs/tools/quickstart/advanced-usage/operation-modes.mdx @@ -53,4 +53,4 @@ With manual close enabled, ledgers only advance when you explicitly trigger a cl curl "http://localhost:11626/manualclose" ``` -Each `manualclose` invocation advances the ledger by exactly one. Support for closing multiple ledgers per invocation 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). +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). diff --git a/docs/tools/quickstart/advanced-usage/run-command-examples.mdx b/docs/tools/quickstart/advanced-usage/run-command-examples.mdx index b018e09e94..e2fad4a4f1 100644 --- a/docs/tools/quickstart/advanced-usage/run-command-examples.mdx +++ b/docs/tools/quickstart/advanced-usage/run-command-examples.mdx @@ -112,7 +112,7 @@ Start an ephemeral local network with manual ledger close enabled. Ledgers only ```sh docker run -d \ -p "8000:8000" \ - -p "11626:11626" \ + -p "127.0.0.1:11626:11626" \ --name stellar \ stellar/quickstart \ --local \ @@ -126,7 +126,7 @@ docker run -d \ ```powershell docker run -d ` -p "8000:8000" ` - -p "11626:11626" ` + -p "127.0.0.1:11626:11626" ` --name stellar ` stellar/quickstart ` --local ` From b26e9981862607f06dd3d69c9a29663f27cadb8b Mon Sep 17 00:00:00 2001 From: devtechedge Date: Sat, 12 Sep 2026 03:16:48 +0530 Subject: [PATCH 4/6] Clarify manual close config generation and ledgerSeq semantics 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. --- docs/tools/quickstart/advanced-usage/operation-modes.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tools/quickstart/advanced-usage/operation-modes.mdx b/docs/tools/quickstart/advanced-usage/operation-modes.mdx index 1b0d281ae6..d513b2f53e 100644 --- a/docs/tools/quickstart/advanced-usage/operation-modes.mdx +++ b/docs/tools/quickstart/advanced-usage/operation-modes.mdx @@ -45,7 +45,7 @@ Upon launching a persistent mode container for the first time, the launch script ## 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. +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. 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. With manual close enabled, ledgers only advance when you explicitly trigger a close by sending the `manualclose` command to stellar-core's HTTP endpoint on port `11626`: @@ -53,4 +53,4 @@ With manual close enabled, ledgers only advance when you explicitly trigger a cl 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 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). +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). From cad2f5e94eba358218b3b72a2f26c6b62d2b4f8f Mon Sep 17 00:00:00 2001 From: devtechedge Date: Sat, 12 Sep 2026 03:32:04 +0530 Subject: [PATCH 5/6] Scope the manual close flag to the local network prerequisite --- docs/tools/quickstart/advanced-usage/operation-modes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tools/quickstart/advanced-usage/operation-modes.mdx b/docs/tools/quickstart/advanced-usage/operation-modes.mdx index d513b2f53e..c57ffc178c 100644 --- a/docs/tools/quickstart/advanced-usage/operation-modes.mdx +++ b/docs/tools/quickstart/advanced-usage/operation-modes.mdx @@ -45,7 +45,7 @@ Upon launching a persistent mode container for the first time, the launch script ## 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. 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 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. With manual close enabled, ledgers only advance when you explicitly trigger a close by sending the `manualclose` command to stellar-core's HTTP endpoint on port `11626`: From 431e602146f00b36fdf8e408e875fb631766d827 Mon Sep 17 00:00:00 2001 From: Dev M Date: Tue, 15 Sep 2026 04:35:45 +0530 Subject: [PATCH 6/6] Correct manual close scope and drop unreachable parameters --- .../quickstart/advanced-usage/operation-modes.mdx | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/tools/quickstart/advanced-usage/operation-modes.mdx b/docs/tools/quickstart/advanced-usage/operation-modes.mdx index c57ffc178c..4eb28237b4 100644 --- a/docs/tools/quickstart/advanced-usage/operation-modes.mdx +++ b/docs/tools/quickstart/advanced-usage/operation-modes.mdx @@ -45,7 +45,15 @@ Upon launching a persistent mode container for the first time, the launch script ## 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. +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. + +::: With manual close enabled, ledgers only advance when you explicitly trigger a close by sending the `manualclose` command to stellar-core's HTTP endpoint on port `11626`: @@ -53,4 +61,4 @@ With manual close enabled, ledgers only advance when you explicitly trigger a cl 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). +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).