Tillman Mosley IIIThis is a submission for the Build Better on Stellar: Smart Contract Challenge : Create a Tutorial
Your Tutorial
Prerequisites
- A fully registered domain name with an available A record
- Example:
rpc.your_domain.com - You can purchase a domain from Namecheap or any domain registrar
- This domain will be used to create a custom endpoint for your RPC server
- Example:
- An API testing client.
- Recommended: https://httpie.io/
- Alternative: Postman or curl
- This will be used to verify the functionality of your RPC server
Introduction
This tutorial will guide you through the process of deploying your own Soroban RPC (Remote Procedure Call) server on DigitalOcean's Kubernetes platform. Soroban is Stellar's smart contract platform, and having your own RPC server allows you to interact with the Stellar network for smart contract operations without relying on public infrastructure.
Benefits of deploying your own Soroban RPC server:
- Increased reliability and uptime
- Control over server resources and configuration
- Potential for better performance compared to public endpoints
By the end of this tutorial, you'll have a fully functional Soroban RPC server accessible via your custom domain.
Target audience
This tutorial is designed for developers with:
- Intermediate knowledge of Kubernetes
- Basic familiarity with DigitalOcean's cloud platform
- Interest in Stellar blockchain development
While prior experience with these technologies is helpful, we'll provide detailed explanations for each step.
Step by Step Instructions
Step - Create Kubernetes Cluster in DigitalOcean
A Kubernetes cluster on DigitalOcean has one or more node pools. Each node pool consists of a group of identical worker nodes. Worker nodes are built on Droplets. For this tutorial, we can build a cluster with two worker nodes in one node pool.
Create Kubernetes cluster in DigitalOcean
a. Log into your DigitalOcean account and navigate to the Kubernetes section.
b. Click "Create Cluster" and choose the following settings:
- Cluster capacity: 2 GB RAM / 1 vCPU per node
- Node count: 2 nodes (minimum for basic redundancy)
- Datacenter region: Choose the closest to your target users
- Cluster name: e.g., "soroban-rpc-cluster"
c. Click "Create Cluster" and wait for provisioning (this may take several minutes).
Rationale: This cluster configuration provides a balance between cost and reliability for a personal RPC server.
If you want to create a single node cluster, you will have to select a larger node size.
Step - Follow Getting Started with Kubernetes guide under the Overview Tab
While the cluster is being provisioned, we can follow along with the rest of the setup instructions that appear under the Overview tab by clicking on Get Started
Connecting to Kubernetes
The first step in connecting to Kubernetes requires additional applications:
Install doctl
https://docs.digitalocean.com/reference/doctl/how-to/install/
Install kubectl
https://kubernetes.io/docs/tasks/tools/
Install Helm
https://helm.sh/docs/intro/install/
Verify connectivity to Kubernetes
- In the DigitalOcean dashboard, go to your cluster's "Overview" tab
- Click "Get Started" and copy the provided doctl command
- Run this command in your terminal to configure kubectl
Rationale: These tools are essential for managing your Kubernetes cluster and deploying applications.
Connect to Your Newly Provisioned Cluster Using doctl
Verify Connectivity
kubectl cluster-info
Display addresses of the control plane and cluster services
doctl kubernetes cluster list
Displays a variety of commands that help manage your cluster via DigitalOcean's API
Step - Add SDF Helm Chart Repository
Stellar Development Foundation (SDF) provides Helm charts for easy deployment of Stellar applications.
Add SDF Helm Chart Repository to Your System:
We will first need to add the Helm Chart repository to our system using the following helm commands:
The helm repo add command adds the chart repository to your local Helm registry
helm repo add stellar https://helm.stellar.org/charts
The helm repo update command updates the information of available charts locally from the chart repositories you have added to your Helm registry.
helm repo update
Rationale: This step allows you to easily install and manage Stellar applications on your Kubernetes cluster.
Step - Deploy Soroban RPC Workload
Now that we have added the SDF chart repository to our local registry and updated the charts that are available to us, we can now deploy a workload using one of the charts available.
a. Create a local deployment configuration file:
- Start with the testnet configuration: https://github.com/stellar/helm-charts/blob/main/charts/soroban-rpc/testnet-values.yaml
- Save this as soroban-rpc-values.yaml on your local machine
Since we will be connecting our RPC server to testnet, we can uncomment update Soroban RPC image tag to the latest version
sorbanRpc:
....
tag: latest
For the ingress section in the configuration file, add your fully registered domain name for the host value
host: rpc.your_domain
We also want to uncomment and update the Ingress class name
ingressClassName:nginx
After we have finished with our configuration file, we can use that to install Soroban RPC into our Kubernetes cluster
helm install my-soroban-rpc stellar/soroban-rpc --values=testnet-values.yaml
Rationale: This configuration sets up your RPC server to use the latest version and prepares it for public access via your domain.
Step - Verify the Service Is Up and Running
Check the status of your service
kubectl get service
Check the status of your pods
kubectl get pods
You should see pods related to Soroban RPC in a "Running" state.
Step - Installing the Kubernetes Nginx Ingress Controller
Even though we have verified that our service is running on our cluster in the previous step, we still cannot access the service from the outside. For that we will need to create an ingress, an ingress is a way for us to expose our service to the outside world. We will use the nginx ingress and we will first need to add the Nginx Helm Chart Repository to our system.
The Nginx Ingress Controller manages external access to your services.
Add Nginx Ingress Helm Chart Repository to Your System:
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update
We can now install the nginx ingress into our Kubernetes cluster
helm install nginx-ingress ingress-nginx/ingress-nginx --set controller.publishService.enabled=true
Run this command to watch the load balancer become available. This process creates a load balancer in the cluster resource group in DigitalOcean.
kubectl --namespace default get services -o wide -w nginx-ingress-ingress-nginx-controller
Rationale: The Ingress Controller allows external traffic to reach your RPC server securely.
Step - Update DNS records to point to DigitalOcean loadbalancer
a. Go to your domain registrar's DNS management page.
b. Create an A record:
- Name: rpc (or your chosen subdomain)
- Value: The External-IP from the previous step
c. Save the changes and wait for DNS propagation (can take up to 48 hours, but often much faster).
Rationale: This step connects your domain name to the DigitalOcean load balancer, allowing access to your RPC server.
Step - Verify You Can Connect to RPC Service Through Your Fully Qualified Domain
Once DNS has propagated, test your RPC server:
http POST https://rpc.your_domain jsonrpc="2.0" id=867 method="getHealth"
Step - Cleanup
If you need to remove the deployment:
Delete Helm releases
helm uninstall soroban-rpc helm uninstall nginx-ingress
Delete the Kubernetes cluster in the DigitalOcean dashboard.
Remove the DNS A record from your domain registrar.
Maintenance Tips
Regularly update your Soroban RPC server:
helm repo update helm upgrade soroban-rpc stellar/soroban-rpc -f soroban-rpc-values.yaml
Monitor cluster health using DigitalOcean's dashboard or kubectl commands.
Set up log aggregation for easier troubleshooting.
Additional Resources:
https://docs.digitalocean.com/products/kubernetes/how-to/create-clusters/#create-a-cluster-using-the-control-panel
https://www.digitalocean.com/community/tutorials/how-to-set-up-an-nginx-ingress-on-digitalocean-kubernetes-using-helm
https://docs.digitalocean.com/products/kubernetes/getting-started/operational-readiness/enable-https/
https://github.com/stellar/helm-charts/
https://soroban.stellar.org/docs
What I Created
This tutorial guides developers through deploying a personal Soroban RPC (Remote Procedure Call) server on DigitalOcean's Kubernetes platform. This is valuable in a few ways:
- Independence: Run your own infrastructure for interacting with the Stellar network's smart contract platform, reducing reliance on public endpoints.
- Reliability: Gain increased uptime and availability by controlling your own server.
- Performance: Potentially achieve better performance compared to shared public endpoints.
- Customization: Have full control over server resources and configuration to suit your specific needs.
- Learning: Gain practical experience with Kubernetes, DigitalOcean, and Stellar's infrastructure.
- Security: Manage your own secure endpoint for sensitive smart contract operations.
By following this tutorial, developers can set up a production-ready Soroban RPC server, accessible via a custom domain, enhancing their ability to build and interact with Stellar smart contracts reliably and efficiently.
Journey
I just tried to work through the same process most developers would take when trying to get an RPC server deployed. That means walking through the process manually and verifying each step along the way.
For developers who want to dive straight into the magic of their own projects without the complexities of infrastructure management, we recommend checking out OBSRVR.
OBSRVR is an SCF (Stellar Community Fund) funded project designed to provide managed Soroban RPC services.
Team: tillman_mosleyiii
