diff --git a/docs/tools/quickstart/advanced-usage/operation-modes.mdx b/docs/tools/quickstart/advanced-usage/operation-modes.mdx index a87779f84b..4eb28237b4 100644 --- a/docs/tools/quickstart/advanced-usage/operation-modes.mdx +++ b/docs/tools/quickstart/advanced-usage/operation-modes.mdx @@ -42,3 +42,23 @@ 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. (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`: + +```sh +curl "http://localhost:11626/manualclose" +``` + +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). diff --git a/docs/tools/quickstart/advanced-usage/run-command-examples.mdx b/docs/tools/quickstart/advanced-usage/run-command-examples.mdx index 532a332fae..e2fad4a4f1 100644 --- a/docs/tools/quickstart/advanced-usage/run-command-examples.mdx +++ b/docs/tools/quickstart/advanced-usage/run-command-examples.mdx @@ -102,3 +102,37 @@ 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" \ + -p "127.0.0.1:11626:11626" \ + --name stellar \ + stellar/quickstart \ + --local \ + --enable-core-manual-close +``` + + + + + +```powershell +docker run -d ` + -p "8000:8000" ` + -p "127.0.0.1:11626:11626" ` + --name stellar ` + stellar/quickstart ` + --local ` + --enable-core-manual-close +``` + + + +