Skip to content

Latest commit

 

History

History
255 lines (210 loc) · 8.95 KB

running_api_from_source.md

File metadata and controls

255 lines (210 loc) · 8.95 KB
Raw

Running a stacks-blockchain API instance from source

In this document, we'll go over how to run a stacks-blockchain-api instance.
There are several components involved here to have a working setup, and we'll go over each.
Please note that the following guide is targeted for Debian based systems - that in mind, most of the commands will work on other Unix systems with some small adjustments.

Requirements

  1. bash or some other Unix-like shell (i.e. zsh)
  2. sudo or root level access to the system

Initial Setup

Since we'll need to create some files/dirs for persistent data,
we'll first create a base directory structure and set some permissions:

$ sudo mkdir -p /stacks-node/{persistent-data/stacks-blockchain,config,binaries}
$ sudo chown -R $(whoami) /stacks-node 
$ cd /stacks-node

Install Requirements

$ PG_VERSION=14 \
  && NODE_VERSION=16 \
  && sudo apt-get update \
  && sudo apt-get install -y \
    gnupg2 \
    git \
    lsb-release \
    curl \
    jq \
    openjdk-11-jre-headless \
    build-essential \
    zip \
  && curl -sL https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add - \
  && echo "deb http://apt.postgresql.org/pub/repos/apt/ `lsb_release -cs`-pgdg main" | sudo tee -a /etc/apt/sources.list.d/pgsql.list \
  && curl -sL https://deb.nodesource.com/setup_${NODE_VERSION}.x | sudo bash - \
  && sudo apt-get update \
  && sudo apt-get install -y \
    postgresql-${PG_VERSION} \
    postgresql-client-${PG_VERSION} \
    nodejs

postgres

postgres permissions

We'll need to set a basic role, database to store data, and a password for the role.
Clearly, this password is insecure so modify password to something stronger before creating the role.

$ cat <<EOF> /tmp/file.sql
create role stacks login password 'password';
create database stacks_db;
grant all on database stacks_db to stacks;
EOF
$ sudo su - postgres -c "psql -f /tmp/file.sql" && rm -f /tmp/file.sql
$ echo "local   all             stacks                                  md5" | sudo tee -a /etc/postgresql/14/main/pg_hba.conf
$ sudo systemctl restart postgresql

stopping postgres

$ sudo systemctl stop postgresql

stacks-blockchain-api

building stacks-blockchain-api

$ git clone https://github.com/hirosystems/stacks-blockchain-api /stacks-node/stacks-blockchain-api && cd /stacks-node/stacks-blockchain-api \
  && echo "GIT_TAG=$(git tag --points-at HEAD)" >> .env \
  && npm install \
  && npm run build \
  && npm prune --production

starting stacks-blockchain-api

The stacks blockchain api requires several Environment Variables to be set in order to run properly.
To reduce complexity, we're going to create a .env file that we'll use for these env vars.

Create a new file: /stacks-node/stacks-blockchain-api/.env with the following content:

$ cat <<EOF> /stacks-node/stacks-blockchain-api/.env
NODE_ENV=production
GIT_TAG=master
PG_HOST=localhost
PG_PORT=5432
PG_USER=stacks
PG_PASSWORD=password
PG_DATABASE=stacks_db
STACKS_CHAIN_ID=0x00000001
V2_POX_MIN_AMOUNT_USTX=90000000260
STACKS_CORE_EVENT_PORT=3700
STACKS_CORE_EVENT_HOST=0.0.0.0
STACKS_BLOCKCHAIN_API_PORT=3999
STACKS_BLOCKCHAIN_API_HOST=0.0.0.0
STACKS_CORE_RPC_HOST=localhost
STACKS_CORE_RPC_PORT=20443
EOF
$ cd /stacks-node/stacks-blockchain-api && nohup node ./lib/index.js &

stopping stacks-blockchain-api

$ ps -ef | grep "lib/index.js" | grep -v grep
user   17788   827 39 18:14 pts/0    00:07:55 node ./lib/index.js
$ sudo kill $(ps -ef | grep "lib/index.js" | grep -v grep | awk {'print $2'})

stacks-blockchain

In order to have a usable API instance, it needs to have data from a running stacks-blockchain instance.

You will need to have the following in your Config.toml - this config block will send blockchain events to the API instance that was previously started:

[[events_observer]]
endpoint = "<fqdn>:3700"
retry_count = 255
events_keys = ["*"]

Here is an example Config.toml that you can use - create this file as /stacks-node/config/Config.toml:

$ cat <<EOF> /stacks-node/config/Config.toml
[node]
working_dir = "/stacks-node/persistent-data/stacks-blockchain"
rpc_bind = "0.0.0.0:20443"
p2p_bind = "0.0.0.0:20444"
bootstrap_node = "02196f005965cebe6ddc3901b7b1cc1aa7a88f305bb8c5893456b8f9a605923893@seed.mainnet.hiro.so:20444"
wait_time_for_microblocks = 10000

[[events_observer]]
endpoint = "localhost:3700"
retry_count = 255
events_keys = ["*"]

[burnchain]
chain = "bitcoin"
mode = "mainnet"
peer_host = "bitcoind.stacks.co"
username = "blockstack"
password = "blockstacksystem"
rpc_port = 8332
peer_port = 8333
EOF

stacks-blockchain binaries

  1. Download latest release binary from https://github.com/blockstack/stacks-blockchain/releases/latest
  • Linux archive for latest release: curl -L https://github.com/blockstack/stacks-blockchain/releases/download/$(curl --silent https://api.github.com/repos/blockstack/stacks-blockchain/releases/latest | jq .name -r | cut -f2 -d " ")/linux-x64.zip -o /tmp/linux-x64.zip
  1. Extract the zip archive: unzip /tmp/linux-x64.zip -d /stacks-node/binaries/

starting stacks-blockchain

$ cd /stacks-node && nohup /stacks-node/binaries/stacks-node start --config /stacks-node/config/Config.toml &

stopping stacks-blockchain

$ ps -ef | grep "/stacks-node/binaries/stacks-node" | grep -v grep
user   17835 17834 99 18:17 pts/0    00:20:23 /stacks-node/binaries/stacks-node start --config /stacks-node/config/Config.toml
$ sudo kill $(ps -ef | grep "/stacks-node/binaries/stacks-node" | grep -v grep | awk {'print $2'})

Verify Everything is running correctly

Postgres

To verify the database is ready:

  1. Connect to the DB instance: psql -h localhost -U stacks stacks_db
  2. List current databases: \l
  3. Verify data is being written to the database: select * from blocks limit 1;
  4. Disconnect from the DB : \q

stacks-blockchain testing

$ curl localhost:20443/v2/info | jq
{
  "peer_version": 402653184,
  "pox_consensus": "e99b880a26405d3cda724f4c2b815ca0e7b681a8",
  "burn_block_height": 666201,
  "stable_pox_consensus": "8be2fc9f9156b31af688b9e3c484dc7a26cefc4f",
  "stable_burn_block_height": 666194,
  "server_version": "stacks-node 2.0.11.0.0 (master:bf4a577+, release build, linux [x86_64])",
  "network_id": 1,
  "parent_network_id": 3652501241,
  "stacks_tip_height": 92,
  "stacks_tip": "a251bfa158c7887c575798b79c8df57190690e023af245e45513110399c0cb5f",
  "stacks_tip_consensus_hash": "ae29e81af9e7febfd4af6b53a3e515660a84150c",
  "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b",
  "unanchored_tip": "9fb08dd696d4e05bd042998dba8dd204ee64e11266cd4fba95b3a7bdaa709400",
  "unanchored_seq": 0,
  "exit_at_block_height": null
}

stacks-blockchain-api testing

$ curl localhost:3999/v2/info | jq
{
  "peer_version": 402653184,
  "pox_consensus": "e99b880a26405d3cda724f4c2b815ca0e7b681a8",
  "burn_block_height": 666201,
  "stable_pox_consensus": "8be2fc9f9156b31af688b9e3c484dc7a26cefc4f",
  "stable_burn_block_height": 666194,
  "server_version": "stacks-node 2.0.11.0.0 (master:bf4a577+, release build, linux [x86_64])",
  "network_id": 1,
  "parent_network_id": 3652501241,
  "stacks_tip_height": 93,
  "stacks_tip": "74223951b9dddfe82b1b116c852f0a14ff9432270d680042a5ef11cb0533b935",
  "stacks_tip_consensus_hash": "2d521daf879f2e00f745c47000b856e1d41b15d4",
  "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b",
  "unanchored_tip": "9fb08dd696d4e05bd042998dba8dd204ee64e11266cd4fba95b3a7bdaa709400",
  "unanchored_seq": 0,
  "exit_at_block_height": null
}