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:
- Run an interactive session of the container at first, ensuring that all services start and run correctly.
- Shut down the interactive container (using Ctrl-C).
- Start a new container using the same host directory in the background.