Building Stellar Apps

An adventure in PostgreSQL and GraphQL

Over the past year, I’ve built three successful Stellar applications of varying complexity.

Colorglyph

Popcoin - Let's get you paid

Stellar Pool - Collect free XLM every week

The Stellar SDKs are amazing well written and the documentation is getting better everyday. The communities on Slack, Reddit and StackExchange is vibrant, helpful and excited. As with anything however, especially a relatively complicated technology the ramp up can be slow and it doesn’t take long to hit both knowledge and feature walls.

Across all the apps I’ve worked on this has been becoming more and more true. As you gain a deeper understanding of how something works you begin to collect a pretty solid wishlist for features you wish existed or problems you haven’t figured out how to solve yet.

The biggest most common and glaring issue I’ve run across for both myself and within the community is getting answers to more and more complex and specific questions about the Stellar dataset itself.

Things like:

• List out all accounts who trust USD from issuer X
• Show me all the trustlines for issuer X
• Which accounts haven’t yet set an inflation destination?
• List all accounts ordered by their XLM volume
• Rank accounts based on their level of “trust” throughout the network

The list goes on and on and as you begin to build, these unanswerable questions will plague you. I say unanswerable but of course they actually are in fact answerable, just not by the current SDKs. Currently to dig deeper into the Stellar ecosystem you have to somehow gain access to the distributed Stellar PostgreSQL database itself. This requires spinning up at least a core server if not a horizon instance as well if you’ve got historical questions needing answers.

With Stellar’s Docker repositories this is actually not as painful as it sounds but the real trouble comes when it’s time to get the psql queries ported to the frontend. This requires you to build an API layer.

This is where I was a couple weeks ago. Slowly building out individual endpoints. Each designed to answer a specific set of questions. It very quickly became a massively painful process. Especially for something which wasn’t ultimately the application I actually wanted to build.

Somewhere between the lines and some conversations with some folks on Slack I had an idea. I wonder if there was an open source tool for porting a PostgreSQL database over to GraphQL. I mean they shared a lot of schema similarities and what GraphQL was to the frontend PostgreSQL was to the backend. Surely there might maybe be such a tool.

💥 Enter PostGraphile 💥

Just a few hours of learning and poking around later and I had direct access to the entire core and horizon databases via GraphQL. Needless to say I was floored. I still am.

The rest of this post will be dedicated to getting this system running on your own servers. However if you’re just looking get back to coding I have some publicly available endpoints available so you can get going right away.

Test Net

• Core Database — core-test.gly.sh/graphiql
• Horizon Database—horizon-test.gly.sh/graphiql
• Horizon REST API—api-test.gly.sh (mirror of horizon-testnet.stellar.org)

Public Net

• Core Database — core.gly.sh/graphiql
• Horizon Database — horizon.gly.sh/graphiql
• Horizon REST API — api.gly.sh (mirror of horizon.stellar.org)

Step 1: Create a Server

Getting all this gold running on your own servers is actually cake 🍰 so don’t freak. I’ve done all the work getting a Docker compose system ready. You’ll just install, configure and tweak as needed.

I’ll be walking through setting this up on Ubuntu via Digital Ocean but if it can run Docker you can run in similar fashion.

Be sure and add support for Monitoring and don’t forget to add your SSH access key. *click* Create!

You may find over time your Droplet may need more power than the 2 : 2 I’m currently running but to date that setup has been sufficient for my needs. I do know much lower and you will run into trouble pretty quickly.

Cool. Droplet created.

Step 2: Access and Configure

Now that we’ve got a droplet, let’s access it via SSH.

ssh root@{droplet.ip.address} -i ~/.ssh/{ssh_code_rsa}

Protip: If you’ll be accessing this droplet frequently paste this ssh command to an executable file and put it in your ~/bin/

Access! The rest is easy.

Ensure you’ve got git installed

git --version

If you get an output to the tune of git version 2.7.4 you should be golden, otherwise just Google how to install git for your OS.

Now we need to add Docker and Docker compose. The instructions on these will probably vary a bit for your OS so I’m going to advise you rely on official, up-to-date documentation for this step. I’ll share what I ran for Ubuntu when I was getting going but it very probably could be different.

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
apt-get update
apt-cache policy docker-ce
apt-get install -y docker-ce
systemctl status docker

I’ll be honest I have no idea what half of those commands actually do or which ones are actually required to run. It’s basically just a copy from this DO article. I just know if that last command outputs something like this you’re golden:

Next up Docker compose.

curl -L https://github.com/docker/compose/releases/download/1.19.0/docker-compose-`uname -s`-`uname -m` -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose
docker-compose --version

Get something like this: docker-compose version 1.19.0, build 9e633ef? No? Quit and reenter the shell and give it another go. 😬

Assuming that all went 💯, and this may be unique to Ubuntu but I’d imagine all OSs have something similar, we need to get into the root directory. On Ubuntu this is simply:

cd ~

When you SSH in it will automatically drop you here, but I like to be sure.

Next you need to clone my Docker compose repo.

git clone https://github.com/TinyAnvil/glysh-docker.git

Sweet, now let’s jump into that new directory.

cd glysh-docker

Rad. Now let’s config just a tiny bit.

nano example.env

This will open a nano editor (feel free to use vim if you’re a nerd 🤓). From here just edit the TESTNET_PASS and PUBNET_PASS environment variables. These will be the passwords for the Stellar PostgreSQL stellar users. Save this file.

Now simply rename this file from example.env to just good ole .env

mv example.env .env

Yay! You’re finally just one command away from all the access you desire!

docker-compose up -d

This will do stuff and with any luck after about a minute or so you should have everything setup to view all the test and public GraphQL endpoints for accessing the Stellar PostgreSQL databases.

You can run to check the status of the containers which have been launched.

docker ps -a

If the STATUS’s aren’t all some sort of “Up” you may need to try shutting down and starting again.

docker-compose down
docker-compose up -d

You’ll also notice all the open ports for accessing your endpoints. 3001, 4001 and 5001 for the testnet and 3000, 4000 and 5000 for public network. Go ahead and visit these to see what you’ve got cooking.

• http://{your-droplet-ip}:3001 (horizon rest api)
• http://{your-droplet-ip}:4001/graphiql (core db)
• http://{your-droplet-ip}:5001/graphiql (horizon db)

Note: It can take a few minutes to a few hours to sync with all the other Stellar nodes so be patient while everything catches up. Be sure and browse around this Stellar repo for information on monitoring your instances.

Conclusion

Well hopefully at this point you’re as ecstatic as I still am. Having such close and direct access to the Stellar databases is incredible. Your frontend development especially will never be the same. 💥 🎉 🎈

If you’ve enjoyed this article be sure and give me a clap or two. Also be sure and reach out with any feedback or suggestions. All the code I’ve written for this is open source and I’d love help making it better.

• https://github.com/TinyAnvil/glysh-docker
• https://github.com/TinyAnvil/postgraphile-docker

Finally be sure and help spread that word, this truly is a game changer for Stellar app development and everyone needs to hear about it.

• Slack—@tyler
• Twitter—@tyvdh
• Email—hi@tyler.chat