Skip to main content

Operation Modes

Background vs. Interactive containers​

Docker containers can be run interactively (using the -it flags) or in a detached, background state (using the -d flag). Many of the example commands below use the -it flags to aid in debugging but in many cases, you will simply want to run a node in the background. It's recommended that you use the guides at docker to familiarize yourself with using docker.

Ephemeral mode​

Ephemeral mode is provided to support development and testing environments. Every time you start a container in ephemeral mode, the database starts empty and a default configuration file will be used for the appropriate network.

Starting an ephemeral node is simple, just craft a docker run command to launch the appropriate image but do not mount a volume. To craft your docker command, you need the network name you intend to run against and the flags to expose the ports you want available (See the section named "Ports" below to learn about exposing ports). Thus, launching a testnet node while exposing Horizon would be:

docker run --rm -it -p "8000:8000" --name stellar stellar/quickstart --testnet

As part of launching, an ephemeral mode container will generate a random password for securing the postgresql service and will output it to standard out. You may use this password (provided you have exposed the postgresql port) to access the running postgresql database.

Persistent mode​

In comparison to ephemeral mode, persistent mode is more complicated to operate, but also more powerful. Persistent mode uses a mounted host volume, a directory on the host machine that is exposed to the running docker container, to store all database data as well as the configuration files used for running services. This allows you to manage and modify these files from the host system.

Note that there is no guarantee that the organization of the files of the volume will remain consistent between releases of the image that occur on every commit to the stellar/quickstart repository. At any time new files may be added, old files removed, or dependencies and references between them changed. For this reason, persistent mode is primarily intended for running short-lived test instances for development. If consistency is required over any period of time use image digest references to pin to a specific build.

Starting a persistent mode container is the same as the ephemeral mode with one exception:

docker run --rm -it -p "8000:8000" -v "/home/scott/stellar:/opt/stellar" --name stellar stellar/quickstart --testnet

The -v option in the example above tells docker to mount the host directory /home/scott/stellar into the container at the /opt/stellar path. You may customize the host directory to any location you like, simply make sure to use the same value every time you launch the container. Also note: an absolute directory path is required. The second portion of the volume mount (/opt/stellar) should never be changed. This special directory is checked by the container to see if it is mounted from the host system which is used to see if we should launch in ephemeral or persistent mode.

Upon launching a persistent mode container for the first time, the launch script will notice that the mounted volume is empty. This will trigger an interactive initialization process to populate the initial configuration for the container. This interactive initialization adds some complications to the setup process because in most cases you won't want to run the container interactively during normal operation, but rather in the background. We recommend the following steps to set up a persistent mode node:

  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:

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.