How to setup a Stellar Horizon server on AWS (EC2 with https)

Task blockchain developer Nik gives me the thumbs up to play with Stellar servers

If you haven’t heard about Stellar, then you should go read a little. It’s a fast, low cost, open-source payment technology that shares several similarities with Ripple (Stellar’s founder Jed McCaleb also co-founded Ripple).

Stellar describes itself as “a platform that connects banks, payments systems, and people. Integrate to move money quickly, reliably, and at almost no cost.”

It’s also the first blockchain technology that Task has adopted — Task is now fully compatible with any Stellar-issued token. Project owners in Task — typically utilised to gather on the ground data and track activities — can reward end users with tokens.

Why is this exciting? Because combined with Task’s verification system (allowing independent assessment of completed task activities), and the token-exchange reward system being released in the coming weeks — Task provides an end to end system to track activity and reward the right behaviours, with localised rewards provided against evidence data locked inside the Stellar ledger system.

Task co-founder Matt when I tried to explain how exciting Stellar tokens are..

What is a Stellar Horizon server?

If you’re reading this post — you probably already know, but “Horizon is an API server for the Stellar ecosystem. It acts as the interface between stellar-core and applications that want to access the Stellar network. It allows you to submit transactions to the network, check the status of accounts, subscribe to event streams, etc.”

Why do we want one?

As we developed Stellar-based token payments on Task, we realised being reliant on the Horizon network would not work, ultimately they don’t provide their infrastructure as a means of delivering production environments — we needed to build our own servers so we can control SLA’s, check and monitor availability and ensure we hit our service speed targets.

Steps to build your Stellar Horizon server

1. Create an EC2 instance on AWS

I created a EC2 instance using Amazon’s Linux AMI — while there are posts suggesting you’ll require a quite powerful instance, feel free to try this out with t2.micro.

Add 20G of storage space, in your security group make sure port 8000 is open, plus port 22 for your ssh access.

2. Define your server hostname

If you want to setup a specific hostname on your server then run

sudo hostnamectl set-hostname webserver.mydomain.com

You check your hostname has been set by running the “hostname” cmd inside the terminal.

3. Setup Docker on the server

A handy post from Mohamed Labouardy helped get Docker installed on the server. Read his full article here, but key steps are:

1. Connect via SSH to the server using the public DNS and the public key
2. Use yum configuration manager to install Docker

sudo yum update -y
sudo yum install -y docker

3. Start the docker service

sudo service docker start

4. Add ec2-user to the docker group so you can use the docker command without root privileges (sudo)

sudo usermod -aG docker ec2-user

IMPORTANT — for these changes to take affect, you must log out of the instance, and ssh back in. Once you’ve ssh’d back in, verify that docker is correctly installed

docker info

4. Install the Stellar Quickstart Docker Image

A supremely useful way to get your Stellar Horizon server running, a well maintained quickstart image is maintained in the Stellar github account.

Go read and absorb everything there. There will be tweaks to your config or other use cases that fall outside of anything I explain here.

Inline with our own purposes, the setup I explain here will:

a) Create a server that runs in persistent mode which “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.”

b) Run off the live public network— it is very easy for you to switch to the test network if you want. Lumens are not a high cost ($0.09 at time of writing), so I personally think testing on the pubnet is often the best way to go.

Run this command to get the quickstart image running:

docker run -it --rm -v "/str:/opt/stellar" --name stellar stellar/quickstart --pubnet

You should see the github repo image fetched, and you’ll be prompted to provide a password for the Postgres database:

You should see the installation complete, the servers come up and that your horizon server has “entered running state”

Control-C to exit the running process.

5. Run the Docker Image as a background process

Previously we ran the docker image in the foreground — which is useful to check that everything was setup correctly, as well as setting up the persistent host directory.

However, now you want to run it as a background persistent container, so that you can logout and leave your Horizon server running on the instance. To do this run:

docker run -d -v "/str:/opt/stellar" -p "8000:8000" --name stellar stellar/quickstart --pubnet

Login to the docker image now running and check your services are with these two commands:

docker exec -it stellar /bin/bash
supervisorctl

You should see something like this:

Cool :) Your Stellar Horizon server is running!

You should be able to view your Horizon server now — if the dynamic public address of your AWS instance is for example “ec2–5–4–3–2.ap-southeast-1.compute.amazonaws.com” then open up the URL “ec2–5–4–3–2.ap-southeast-1.compute.amazonaws.com:8000” in your web browser and you should see something like this:

IMPORTANT: In the JSON output from your Horizon server you can see

"history_latest_ledger": 0,
"history_elder_ledger": 0,
"core_latest_ledger": 1,

It takes time for the ledger to update — in my case I left it for 24 hours and it was up to date, I could not tell you the minimum time for your server to sync…

Setting up DNS and https certification

Due to the intrinsically “encrypted” nature of blockchain, and the fact that Stellar focuses on being a public ledger — there is not a big emphasis on the setup of https.

Thats a big problem for Task — our users are accessing their wallets directing from our mobile applications, and iOS for example refuses to allow non-encrypted URLs. There are different ways to approach this, but the way that made sense for me…

1. Setup an AWS Load Balancer

Really easy to — however I ran into trouble trying get the mapping to work, so I started again and chose the Classic Load Balancer:

On the next page map the HTTPS port 443 to your instances’ HTTP port 8000 which is where you’ve got your Horizon server running.

Create a new security group that allows ports 443 through the Load Balancer.

Next up — create a free SSL certificate in your AWS console. Its very easy to do, navigate to the Certificate Manager page. There’s plenty of tutorials about on how to do this so I won’t add more here.

One area I did run into trouble was setting up the Health Check, but it was an easy fix. Changing the Ping Path value from “/index.html” to just “/” fixed it for me.

Finally, attach your instance to the Load Balancer and save. Your Load Balancer should be live in a few minutes.

2. Configure DNS using Route53

Finally, create a new record set in your Route 53 zone records for your domain:

• Specify your subdomain such stellar-horizon.your-domain.com
• Type = A-IPv4 Address
• Alias = Yes
• Alias Target — look under the ELB Classic Load Balancers and select your new load balancer

Save… and go take a look at https://stellar-horizon.your-domain.com or whatever you setup.

Thoughts and close out

When I first sent this live, it took a little time before I could access the box (initially it displayed a 503 error). I noticed I had a “bad” health check on the load balancer, and I fixed it using the technique explained — it burst into life after that.

We have lots more testing to do — and will be delving into the art of managing Stellar Horizon servers and nodes in the coming months. This is a work in progress, and we’re going through a big learning phase right now.

I’m really excited about how we have interwoven blockchain technology into the Task platform. The manner in which it allows anyone to use Task to create immutably trackable reward systems is innovative — Task permits all sorts of different data gathering and activity tracking use cases, but the two great benefits that Stellar brings, namely: ledger security and low-cost payments extend Task as a platform beyond traditional reaches.

I hope this article is of use to other developers looking to interact with the Stellar network. We’re really keen to connect to like-minded people out there who are interested in what Task does and can be.

If you enjoyed this story, please click the 👏 button and share to help others find it. Feel free to leave a comment below.

Task is a platform that connects organisations to individuals so that projects can be outsourced via mobile devices in the form of auditable tasks. Organisations collect business critical data, which along with Task’s verification and proof of work capabilities, allow individuals to be rewarded for taking part. Please visit our website and get involved.