Where to begin

You’re ready to start. You’ve read about data-centric systems or have an idea for a Web3 service and discovered Fluree is the right way to get started. You’ve downloaded Fluree, starred it on Github, and reviewed the docs. Now what? 

Should you just start building, or plan your project out first with an architectural diagram? You may be wondering about the risks associated with diving in headfirst: what if the components you have chosen don’t scale easily, or at all? 

I’m Jake, a platform engineer at Fluree, and in this post, I’m going to show how easy it is to get started with Fluree and still have confidence that it will grow with you and scale to meet your system requirements. 

You can start working with Fluree On-Demand right away. But if you want to work towards your own custom fluree deployment, below are some options for Fluree Anywhere. 

What do we mean by Walk, Crawl, Run?

Crawl – Getting Started with Fluree Anywhere

Getting started with Fluree Anywhere doesn’t mean you have to architect for distributed computing from the start. You can step into it. You can start with an all-in-one standalone version that includes everything in one package. Even though this is one package, it includes:

• The ledger server that allows you to write transactions to an immutable ledger.
• The query server that handles your requests for questions to the database.
• A web admin console to allow you to directly write your transactions and queries, create users and monitor your server.

Walk – Starting to Grow

As you start to grow your system, you might want to add more query servers in order to scale your ability to handle an increase in demand generated by your users. You might also create a React or NodeJS app to communicate with the ledger. This new layer allows you to control how your users or administrators view the data or create new data.

Run – Scaling Out

Lastly in the run stage, you may need to scale your ledger servers. You might want to build a server cluster to handle losing one or more ledger servers, or you are starting to create multiple ledgers that have their transactions handled by this cluster.

I like to use Docker for all of these deployments. It helps with dependency management and ensures I’m not running something that could conflict with Fluree. This is especially true on my local workstation, maybe less so on a single-purpose server. But if you have JDK ≥ 11 setup, you can use our download and start the ledger server directly.

Below, I’ll show you a simple Crawl → Walk → Run progression for both local and cloud deployments of Fluree-Anywhere.  Local would represent how you might provision Fluree in your own data center or  server(s), and cloud represents how you may use a third-party to deploy and scale Fluree.

Local

Crawl

If you have Docker Desktop running already you can run Fluree without installing anything else.

docker run -p 8090:8090 fluree/ledger:v1.0.0-beta8

This will start an ephemeral instance of Fluree and you’ll be able to see the log output to the screen.

Once it is running, you can visit http://localhost:8090 to see the admin UI.

If you go to another terminal window while Fluree is running, you can run docker ps to see the container id. With it you can run:

docker stop [container_id]

and:

docker start [container_id]

I like to create a folder on my host machine so that when I start creating data and want to keep it, I can use it with new Docker containers later on.

mkdir ~/fluree_data

docker run -v /Users/username/ledger_data/:/var/lib/fluree -p 8090:8090 

fluree/ledger:v1.0.0-beta8

Of course, you don’t need Docker. If you have java jdk >= 11, you can follow the instructions and install Fluree from the download.

Walk

Once you are comfortable working with the admin UI and are able to create and query data, you’ll probably want to start development on an app to connect to Fluree. You can review the API endpoints here and use a tool like Postman to simulate how your app might consume and transact with Fluree.

If you’re working with React, you could start with our cra-template

If your app is taking on too much load from all of the queries that are taking place, it might be time to add a query server in front of the all-in-one you are running. You can run one or more instances of our nodejs server.

Run

If you need higher availability on the transaction side, you will start thinking about running more instances of the ledger server. Our ledger servers are able to run in a group and use a raft consensus algorithm in order to maintain consistency across nodes.

If you start with 3 nodes, you can lose one and still be operational.

Our Docker Fluree Example repo has a docker-compose.cluster.yml file that displays how this can be done.

If you have docker-compose you can run this directly:

 docker-compose -f docker-compose.cluster.yml up

Even if you aren’t using Docker, you can see in the file the environment variables that you can use for each instance of the ledger server to group them together.

Cloud

Running Fluree in your own cloud has similar steps going from a crawl to walk to run. The cloud is someone else’s servers, after all.

Crawl

To get started, you can spin up an EC2 instance at AWS or a Droplet at DigitalOcean or wherever you want to launch a VM. From there you can install java jdk >= 11 and download and install Fluree. Or you can install Docker and run the all-in-one version of the ledger server as we did above. Note that Fluree will run on port 8090 unless you specify otherwise, and you’ll need to add that to a public url http://exampleurl.com:8090 to be able to access your running admin UI.

Walk

Because Fluree uses web communications through HTTP and Web Sockets, scaling with readily-available web tools is straightforward.

For the walk stage in the cloud, I would put the ledger server behind a load balancer or a proxy to control web traffic to it. You can still run the single instance, but a load balancer will give you added protection against DDOS attacks, etc. 

Also, you can add the nodejs query server like I explained above in the local “walk” section and put the ledger server on a private network with traffic only coming from the query server(s).

Run

If you’re requiring even more availability and cannot afford any downtime, like in the local run section, you can create a group of ledger servers and connect them together in a cluster. It would make sense to put some of them in different availability zones to avoid a data center outage.

You’ll also want to put your query servers behind a load balancer that can auto-scale out as far as you’d like.

---

Summary

You don’t have to start with a complicated system to begin building with Fluree. Getting started with the Crawl steps can help you build a solid mental model of how everything works before solidifying your growth plans.

Just know that Fluree can scale with you as your needs demand it.

I’m a fan of infrastructure-as-code and would recommend looking into Terraform, AWS Cdk, or Pulimi once you get past the crawl stage of cloud deployment.

Thanks for taking the time to read more about Fluree!

---