Welcome!

Stellar - Getting Started

Difficulty:Beginner

Estimated Time:10 minutes

Ready for faster, cheaper transactions? In this tutorial we will see how stellar works and the steps to run it using docker. Understand the major Stellar concepts, like consensus, trust and credit, etc. The stellar business model and stellar.org along with addressing how to perform the easy and rapid transactions.

Congratulations!

You've completed the scenario!

Scenario Rating

All these Stellar Cores—the network of nodes—eventually agree on sets of transactions. Each transaction on the network costs a small fee: 100 stroops (0.00001 XLM). This fee helps prevent bad actors from spamming the network. The Stellar network refers to the technology that processes financial transactions. The technology is open source, distributed, and community owned. Stellar.org is the nonprofit organization that contributes to the development of tools and social good initiatives around the Stellar network and financial inclusion. Employees contribute code to the Stellar network, but the technology is independent of the organization. Though transactions require an Internet connection at the moment, tools for low-bandwidth environments are in development.

Steps

Stellar - Getting Started

Step1 of 5

Stellar Network Overview

How the Stellar network operates ? How do you send USD to your friend using INR on stellar network ? Let's start with the concept with a small scenario.

The Internet is made up of network servers containing our data, websites and applications. Like the Internet, Stellar is a network of decentralized servers in many locations that power the distributed ledger. This ledger records every transaction in the system for people and companies alike. A complete copy of the global ledger exits on each Stellar server. Any entity can run a server. The network becomes more robust with more servers. The server communicates with each other to verify transactions and sync the ledger every 2-5 seconds. This mechanism is called consensus. The ledger record your money as credit, which i issued by anchors. Anchor acts as bridges between the given currency and Stellar network. Banks and Payment processors are good examples of real anchors. Credit is issued to your online account - which act as a virtual wallet - in exchange for your deposit. Anchors have to be trusted to hold your money and honor your withdrawals. Issued credit can be send and received to people on the network. Stellar has a distributed exchange, so you can send USD credits to your friend using your INR credit balance. The network will automatically convert it with the lowest rate for you. Your friend will receive USD credit, which she can withdraw using an anchor supporting USD.

Using the Stellar network, we can build mobile wallets, banking tools, smart devices that pay for themselves, and just about anything else you can dream up involving payments! Even though Stellar is a complex distributed system, working with it doesn’t need to be complicated.

API: Horizon

Most applications interact with the Stellar network through Horizon, a RESTful HTTP API server. Horizon gives you a straightforward way to submit transactions, check accounts, and subscribe to events. Because it’s just HTTP, you can communicate with Horizon using your web browser, simple command line tools like cURL, or the Stellar SDK for your favorite programming language.

Stellar.org maintains JavaScript, Java, and Go-based SDKs for communicating with Horizon. There are also community-maintained SDKs for Ruby, Python, and C#.

Network Backbone: Stellar Core

Behind the scenes, every Horizon server connects to Stellar Core, the backbone of the Stellar network. The Stellar Core software does the hard work of validating and agreeing with other instances of Core on the status of every transaction through the Stellar Consensus Protocol (SCP). The Stellar network itself is a collection of connected Stellar Cores run by various individuals and entities around the world. Some instances have a Horizon server you can communicate with, while others exist only to add reliability to the overall network.

Stellar Quickstart Docker Image

Stellar provides a simple way to incorporate stellar-core and horizon into your private infrastructure, provided that you use docker.

This image provide a default, non-validating, ephemeral configuration that should work for most developers. By configuring a container using this image with a host-based volume an operator gains access to full configuration customization and persistence of data.

The image uses the following software:

1) Postgresql 9.5 is used for storing both stellar-core and horizon data
2) stellar-core
3) horizon
4) Supervisord is used from managing the processes of the services above.

First, decide whether you want your container to be part of the public, production Stellar network (referred to as the pubnet) or the test network (called testnet) that we recommend you use while developing software because you need not worry about losing money on the testnet. You'll provide either --pubnet or --testnet as a command line flag when starting the container to determine which network (and base configuration file) to use.

Next, you must decide whether you will use a docker volume or not. When not using a volume, we say that the container is in ephemeral mode, that is, nothing will be persisted between runs of the container. Persistent mode is the alternative, which should be used in the case that you need to either customize your configuration (such as to add a validation seed) or would like avoid a slow catchup to the Stellar network in the case of a crash or server restart. We recommend persistent mode for anything besides a development or test environment.

Finally, you must decide what ports to expose. The software in these images listen on 4 ports, each of which you may or may not want to expose to the network your host system is connected to. A container that exposes no ports isn't very useful, so we recommend at a minimum you expose the horizon http port.

The -v option in the example above tells docker to mount the host directory /home/mohan/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.

Customizing Configurations

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 setup 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.

To customize the configurations that both stellar-core and horizon use, you must use persistent mode. The default configurations will be copied into the data directory upon launching a persistent mode container for the first time. Use the diagram below to learn about the various configuration files that can be customized.

Image

It is recommended that you stop the container before editing any of these files, then restart the container after completing your customization.

NOTE: Be wary of editing these files. It is possible to break the services started within this container with an bad edit. It's recommended that you learn about managing the operations of each of the services before customizing them, as you are taking responsibility for maintaining those services going forward.

Ports

Port | Service | Description

5432 | postgresql | database access port

8000 | horizon | main http port

11625 | stellar-core | main http port

11626 | stellar-core | peer node port

Security Considerations

Exposing the network ports used by your running container comes with potential risks. While many attacks are preventable due to the nature of the stellar network, it is extremely important that you maintain protected access to the postgresql server that runs within a quickstart container. An attacker who gains write access to this DB will be able to corrupt your view of the stellar network, potentially inserting fake transactions, accounts, etc.

It is safe to open the horizon http port. Horizon is designed to listen on an internet-facing interface and has provides no privileged operations on the port.

The HTTP port for stellar-core should only be exposed to a trusted network, as it provides no security itself. An attacker that can make requests to the port will be able to perform administrative commands such as forcing a catchup or changing the logging level and more, many of which could be used to distrupt operations or deny service.

The peer port for stellar-core however can be exposed, and ideally would be routable from the internet. This would allow external peers to initiate connections to your node, improving connectivity of the overlay network. However, this is not required as your container will also establish outgoing connections to peers.

Debugging a Running Container

There will come a time when you want to inspect the running container, either to debug one of the services, to review logs, or perhaps some other administrative tasks. We do this by starting a new interactive shell inside the running container:

docker exec -it stellar /bin/bash

The command above assumes that you launched your container with the name stellar; Replace that name with whatever you chose if different. When run, it will open an interactive shell running as root within the container.

Restarting services

Services within the quickstart container are managed using supervisord and we recommend you use supervisor's shell to interact with running services. To launch the supervisor shell, open an interactive shell to the container and then run supervisorctl. You should then see a command prompt that looks like:

supervisorctl

Note : If you receive error as unix:///var/run/supervisor.sock no such file then apparently run "service supervisord start" doesn't necessarily load your config file, or even a config file at all. In order to make it work, I had to do a supervisord -c /stellar/supervisor/etc/config.conf (i.e. run the binary directly) this fixed the error.

restart horizon

restart horizon

stop stellar-core

stop stellar-core

You can learn more about what commands are available by using the help command.

Viewing logs

Logs can be found within the container at the path /var/log/supervisor/. A file is kept for both the stdout and stderr of the processes managed by supervisord. Additionally, you can use the tail command provided by supervisorctl.

Accessing databases

The point of this project is to make running stellar's software within your own infrastructure easier, so that your software can more easily integrate with the stellar network. In many cases, you can integrate with horizon's REST API, but often times you'll want direct access to the database either horizon or stellar-core provide. This allows you to craft your own custom sql queries against the stellar network data.

This image manages two postgres databases: core for stellar-core's data and horizon for horizon's data. The username to use when connecting with your postgresql client or library is stellar. The password to use is dependent upon the mode your container is running in: Persistent mode uses a password supplied by you and ephemeral mode generates a password and prints it to the console upon container startup.

Multiple Launch Commands

Below is a list of various ways you might want to launch the quickstart container annotated to illustrate what options are enabled. It's also recommended that you should learn and get familiar with the docker command.

Launch an ephemeral pubnet node in the background(Note: In your current scenario stellar is already running, give it another name):

Debugging Scenarios

Help

Katacoda offerings an Interactive Learning Environment for Developers. This course uses a command line and a pre-configured sandboxed environment for you to use. Below are useful commands when working with the environment.

cd <directory>

Change directory

ls

List directory

echo 'contents' > <file>

Write contents to a file

cat <file>

Output contents of file

Vim

In the case of certain exercises you will be required to edit files or text. The best approach is with Vim. Vim has two different modes, one for entering commands (Command Mode) and the other for entering text (Insert Mode). You need to switch between these two modes based on what you want to do. The basic commands are: