README

.gitignore

@@ -2,4 +2,6 @@
 *.tfstate.backup
 *.tfstate.lock.info
 .terraform/
-.envrc
+.envrc
+terraform.tfvars
+.terraform.lock.hcl

README.md

@@ -0,0 +1,50 @@
+# What is this
+
+This repository contains tools for setting up a reliable (private) bittensor subtensor and a subtensor proxy that 
+works as a drop in replacement for regular subtensors, consumes minimal resources (therefore can and should be 
+run on each node requiring subtensor access) and supports failovers to public subtensors (subvortex and finney)
+in case of private subtensor downtime. The private subtensor deployed using this repo's tools automatically detects 
+being out of sync and disables traffic to it in such a case. If synchronisation is not achieved after a period of time,
+the subtensor will be purged and started anew.
+
+# Usage
+
+## Deploying private subtensor
+
+After setting up a Linode account (together with a payment method) and obtaining a Linode API key run 
+`bash deploy_linode_subtensor.sh`. You will be prompted for the API key and some other deployment details (like an ssh 
+key for the newly created virtual machines). Once the process is done, proceed to your Linode account, go to 
+the `NodeBalancers` tab and copy the address of the newly created NodeBalancer.
+
+## Starting subtensor proxy
+
+While the subtensor mentioned above is ready to use as is, it might fail (as all subtensors might) so for enhanced 
+stability we suggest using a subtensor proxy, deploying it on each node utilizing a subtensor. In case of private
+subtensor failure, the proxy will direct traffic to subvortex and finney, without any changes in  client code (miner,
+validator, btcli etc.). Simply run
+
+```
+docker run --env SUBTENSOR_NODE_ADDRESS=... -p 9944:9944 ghcr.io/bactensor/bt-subtensor-tools/subtensor-proxy
+```
+
+(as value for `SUBTENSOR_NODE_ADDRESS` use the load balancer address as displayed in Linode console, for example
+`105.200.223.24`)
+
+To use the proxy just type `localhost:9944` as your subtensor address, for example when using btcli: 
+
+```
+btcli s metagraph --netuid 1 --subtensor.network localhost:9944
+```
+
+## If your subtensor client (miner, validator) is running in docker
+
+Using `localhost:9944` as subtensor address won't work, due to how docker hahndles networking. The best way is to put 
+the ghcr.io/bactensor/bt-subtensor-tools/subtensor-proxy in the same 
+docker-compose.yml as your miner/validator. For example if you use `subtensor-proxy` as the service name in 
+docker-compose.yml add `subtensor-proxy` in `links` section of your subtensor client (miner or validator) service  
+configuration and use `subtensor-proxy:9944` as the subtensor address.
+
+If you're not using docker-compose you need to find the address of your host machine in docker network (it often is
+`172.17.0.1`). You can do that by listing network interfaces along with addresses, for example using `ip a` and looking
+for sth like `docker0`. After you find that address, pass it as your subtensor address to your subtensor client (miner, 
+validator), for example `172.17.0.1:9944`.

deploy_linode_subtensor.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+
+cd "$(dirname "$0")"
+
+# Check if terraform is installed, if it is not, print a link to installation instructions and exit
+if ! command -v terraform &> /dev/null
+then
+    echo "Terraform could not be found"
+    echo "Please follow the installation instructions at https://learn.hashicorp.com/tutorials/terraform/install-cli"
+    exit 1
+fi
+
+# Check if venv exists, if it doesn't, create it
+if [ ! -d "../bt-subtensor-tools-venv" ]
+then
+    echo "Creating virtual environment..."
+    python3 -m venv ../bt-subtensor-tools-venv
+fi
+
+# Activate venv and install requirements.txt
+source ../bt-subtensor-tools-venv/bin/activate
+pip install -r requirements.txt
+
+# Check if infra/.envrc exists, if not, create from example and substitute API token
+if [ ! -f "infra/.envrc" ]
+then
+    read -p 'Linode API Token: ' apiToken
+    echo "infra/.envrc not found, creating..."
+    sed "s/export LINODE_TOKEN=.*/export LINODE_TOKEN=$apiToken/" infra/.envrc.example > infra/.envrc
+fi
+
+# Check if terraform.tfvars exists, if not, create from example and substitute SSH key
+if [ ! -f "infra/terraform.tfvars" ]
+then
+    read -p 'SSH key: ' sshKey
+    echo "infra/terraform.tfvars not found, creating..."
+    sed "s/SSH_KEY_HERE/$sshKey/" infra/terraform.tfvars.example > infra/terraform.tfvars
+fi
+
+cd infra
+source .envrc
+terraform init
+terraform apply

requirements.txt

@@ -0,0 +1 @@
+ansible>=10.5.0,<11.0.0