Skip to main content

Installing

There are three common ways to install and run Stellar Core:

  1. Using published packages. For production use, we recommend installing Stellar Core using published packages.

  2. Building from source. In some uncommon situations, or if you want to sacrifice convenience for maximum control, building from source may be necessary.

  3. Use a Docker image. Using a Docker image is the quickest and easiest method, so it's a good choice for a lot of developers.

Release Version​

Whichever method you use, you should make sure to install the latest release since these builds are backwards compatible and are cumulative.

The version number scheme that we follow is protocol_version.release_number.patch_number, where:

  • protocol_version is the maximum protocol version supported by that release (all versions are 100% backward compatible),
  • release_number is bumped when a set of new features or bug fixes not impacting the protocol are included in the release, and
  • patch_number is used when a critical fix has to be deployed.

Package-Based Installation​

If you are using a recent LTS version of Ubuntu, we provide stellar-core and stellar-horizon in Debian binary package format. The packages are cryptographically signed by the Stellar Development Foundation and files can be validated on the system to confirm they were not tampered with. Debian packages utilize operating system built-in cryptographic verification during upgrades which mitigates many supply chain attacks.

SDF package signing key fingerprint is AEAF 01EE A6CA FCEF DDAE 8AA7 0463 8272 A136 B5A6 (A136B5A6)

Currently we do not publish packages for RPM based Linux distributions. If you use such distribution we recommend using docker images

Configure SDF Apt Repository On The System​

sudo install -d /etc/apt/keyrings
sudo curl -fsSL https://apt.stellar.org/SDF.asc -o /etc/apt/keyrings/SDF.asc
sudo chmod a+r /etc/apt/keyrings/SDF.asc
echo "deb [signed-by=/etc/apt/keyrings/SDF.asc] https://apt.stellar.org $(lsb_release -cs) stable" | sudo tee -a /etc/apt/sources.list.d/SDF.list

Optionally you can add testing repository. This is not recommended for production systems but may be useful for non-production systems using testnet:

echo "deb [signed-by=/etc/apt/keyrings/SDF.asc] https://apt.stellar.org $(lsb_release -cs) stable" | sudo tee -a /etc/apt/sources.list.d/SDF.list

Install packages​

We publish multiple packages for convenience.

PackageDependenciesComments
stellar-corenoneinstalls stellar-core binary, systemd service, logrotate script, documentation
stellar-core-utilsnoneinstalls useful command line tools (stellar-core-cmd, stellar-core-gap-detect)
stellar-core-prometheus-exporternoneinstalls a Prometheus exporter to facilitate ingesting stellar-core metrics
stellar-core-postgresstellar-core, PostgreSQLconfigures a PostgreSQL server, creates a stellar db,role and system user, the default stellar-core configuration contained in this package will connect to the Testnet
stellar-archivistnoneinstalls stellar-archivist cli tool for managing stellar-core History archives

To install a chosen package run:

# To install stellar-core
sudo apt-get update && apt-get install <package_name>

Installing From Source​

The Stellar Core source code repository contains extensive and thorough instructions to build the software from source. Please check out INSTALL.md for more information.

Docker-Based Installation​

Development Environments​

SDF maintains a quickstart image that bundles Stellar's "Captive Core" with Horizon and the necessary PostgreSQL databases. It's a quick way to set up a default, non-validating, ephemeral configuration that should work for most developers. Additionally, the quickstart image can be spun up pre-configured for use as a Mainnet, Testnet, Futurenet, or Local network node.

info

The quickstart image is not intended to serve as a production-level instance node. Please plan your production instance(s) carefully.

Production Environments​

SDF also maintains a Stellar-Core-only standalone image, stellar/stellar-core.

Example usage:

docker run stellar/stellar-core:latest help
docker run stellar/stellar-core:latest gen-seed

To run the Stellar Core daemon you need to provide a configuration file:

# Initialize postgres DB (see DATABASE config option)
docker run -v "/path/to/config/dir:/etc/stellar/" stellar/stellar-core:latest new-db
# Run stellar-core daemon in the background
docker run -d -v "/path/to/config/dir:/etc/stellar/" stellar/stellar-core:latest run

The image utilizes deb packages so it's possible to confirm the checksum of the stellar-core binary in the docker image matches what is in the cryptographically signed deb package. See package based installation section for information. To calculate this checksum in the docker image you can run:

docker run --entrypoint=/bin/sha256sum stellar/stellar-core:latest /usr/bin/stellar-core