mirror of https://github.com/lukechilds/docs.git
Patrick Gray
4 years ago
committed by
Patrick Gray
Patrick Gray
3 changed files with 307 additions and 1 deletions
@ -0,0 +1,303 @@ |
|||
--- |
|||
title: Running an API node |
|||
description: Set up and run a local API node with Docker |
|||
icon: MainnetIcon |
|||
images: |
|||
large: /images/pages/mainnet.svg |
|||
sm: /images/pages/mainnet-sm.svg |
|||
--- |
|||
|
|||
## Introduction |
|||
|
|||
This procedure demonstrates how to run a local API node using Docker images. There are several components that must be |
|||
configured and run in a specific order for the local API node to work. |
|||
|
|||
For this procedure, the order in which the services are brought up is very important. In order to start the API node |
|||
successfully, you need to bring up the services in the following order: |
|||
|
|||
1. `postgres` |
|||
2. `stacks-blockchain-api` |
|||
3. `stacks-blockchain` |
|||
|
|||
When bringing down the API node, you should bring the services down in the exact reverse order in which they were |
|||
brought up, to avoid losing data. |
|||
|
|||
-> This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on |
|||
Windows. |
|||
|
|||
## Prerequisites |
|||
|
|||
Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi |
|||
boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software |
|||
installed on the node host machine: |
|||
|
|||
- [Docker](https://docs.docker.com/get-docker/) |
|||
- [curl](https://curl.se/download.html) |
|||
- [psql](http://postgresguide.com/utilities/psql.html) (_installed locally_) |
|||
- [jq](https://stedolan.github.io/jq/download/) |
|||
|
|||
### Firewall configuration |
|||
|
|||
In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on |
|||
the ports discussed in this section. The details of network and firewall configuration are highly specific to your |
|||
machine and network, so a detailed example isn't provided. |
|||
|
|||
The following ports must open on the host machine: |
|||
|
|||
Ingress: |
|||
|
|||
- postgres (open to `localhost` only): |
|||
- `5432 TCP` |
|||
- stacks-blockchain-api |
|||
- `3999 TCP` |
|||
- stacks-blockchain (open to `0.0.0.0/0`): |
|||
- `20443 TCP` |
|||
- `20444 TCP` |
|||
|
|||
Egress: |
|||
|
|||
- `8332` |
|||
- `8333` |
|||
- `20443-20444` |
|||
|
|||
These egress ports are for syncing [`stacks-blockchain`][] and Bitcoin headers. If they're not open, the sync will fail. |
|||
|
|||
## Step 1: initial setup |
|||
|
|||
In order to run the API node, you must download the Docker images and create a directory structure to hold the |
|||
persistent data from the services. Download and configure the Docker images with the following commands: |
|||
|
|||
```sh |
|||
docker pull blockstack/stacks-blockchain-api && docker pull blockstack/stacks-blockchain && docker pull postgres:alpine |
|||
docker network create stacks-blockchain > /dev/null 2>&1 |
|||
``` |
|||
|
|||
Create a directory structure for the service data with the following command: |
|||
|
|||
```sh |
|||
mkdir -p ./stacks-node/{persistent-data/postgres,persistent-data/stacks-blockchain,bns,config} && cd stacks-node |
|||
``` |
|||
|
|||
## Step 2: running Postgres |
|||
|
|||
The `postgres:alpine` Docker container can be run with default settings. You must set the password for the user to |
|||
`postgres` with the `POSTGRES_PASSWORD` environment variable. The following command starts the image: |
|||
|
|||
```sh |
|||
docker run -d --rm \ |
|||
--name postgres \ |
|||
--net=stacks-blockchain \ |
|||
-e POSTGRES_PASSWORD=postgres \ |
|||
-v $(pwd)/persistent-data/postgres:/var/lib/postgresql/data \ |
|||
-p 5432:5432 |
|||
postgres:alpine |
|||
``` |
|||
|
|||
You can verify the running Postgres instance on port `5432` with the command |
|||
|
|||
```sh |
|||
docker ps --filter name=postgres |
|||
``` |
|||
|
|||
## Step 3: running Stacks blockchain API |
|||
|
|||
The [`stacks-blockchain-api`][] image requires several environment variables to be set. To reduce the complexity of the |
|||
run command, you should create a new `.env` file and add the following to it using a text editor: |
|||
|
|||
``` |
|||
NODE_ENV=production |
|||
GIT_TAG=master |
|||
PG_HOST=postgres |
|||
PG_PORT=5432 |
|||
PG_USER=postgres |
|||
PG_PASSWORD=postgres |
|||
PG_DATABASE=postgres |
|||
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_BLOCKCHAIN_API_DB=pg |
|||
STACKS_CORE_RPC_HOST=stacks-blockchain |
|||
STACKS_CORE_RPC_PORT=20443 |
|||
BNS_IMPORT_DIR=/bns-data |
|||
``` |
|||
|
|||
-> This guide configures the API to import BNS data with the `BNS_IMPORT_DIR` variable. To disable this import, comment |
|||
the line out by placing a `#` at the beginning of the line. If you leave the BNS import enabled, it may take several |
|||
minutes for the container to start while it imports the data. |
|||
|
|||
The `PG_HOST` and `STACKS_CORE_RPC_HOST` variables define the container names for `postgres` and `stacks-blockchain`. |
|||
You may wish to alter those values if you have named those containers differently than this guide. |
|||
|
|||
Start the [`stacks-blockchain-api`][] image with the following command: |
|||
|
|||
```sh |
|||
docker run -d --rm \ |
|||
--name stacks-blockchain-api \ |
|||
--net=stacks-blockchain \ |
|||
--env-file $(pwd)/.env \ |
|||
-v $(pwd)/bns:/bns-data \ |
|||
-p 3700:3700 \ |
|||
-p 3999:3999 \ |
|||
blockstack/stacks-blockchain-api |
|||
``` |
|||
|
|||
You can verify the running `stacks-blockchain-api` container with the command: |
|||
|
|||
```sh |
|||
docker ps --filter name=stacks-blockchain-api |
|||
``` |
|||
|
|||
## Step 4: running Stacks blockchain |
|||
|
|||
In order for the API to be functional, the [`stacks-blockchain-api`][] container must have data from a running |
|||
[`stacks-blockchain`][] instance. First create the `./config/Config.toml` file and add the following content to the |
|||
file using a text editor: |
|||
|
|||
```toml |
|||
[node] |
|||
working_dir = "/root/stacks-node/data" |
|||
rpc_bind = "0.0.0.0:20443" |
|||
p2p_bind = "0.0.0.0:20444" |
|||
bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" |
|||
wait_time_for_microblocks = 10000 |
|||
|
|||
[[events_observer]] |
|||
endpoint = "stacks-blockchain-api:3700" |
|||
retry_count = 255 |
|||
events_keys = ["*"] |
|||
|
|||
[burnchain] |
|||
chain = "bitcoin" |
|||
mode = "mainnet" |
|||
peer_host = "bitcoin.blockstack.com" |
|||
username = "blockstack" |
|||
password = "blockstacksystem" |
|||
rpc_port = 8332 |
|||
peer_port = 8333 |
|||
|
|||
[connection_options] |
|||
read_only_call_limit_write_length = 0 |
|||
read_only_call_limit_read_length = 100000 |
|||
read_only_call_limit_write_count = 0 |
|||
read_only_call_limit_read_count = 30 |
|||
read_only_call_limit_runtime = 1000000000 |
|||
``` |
|||
|
|||
The `[[events_observer]]` block configures the instance to send blockchain events to the API container that you |
|||
started previously. |
|||
|
|||
Start the [`stacks-blockchain`][] container with the following command: |
|||
|
|||
```sh |
|||
docker run -d --rm \ |
|||
--name stacks-blockchain \ |
|||
--net=stacks-blockchain \ |
|||
-v $(pwd)/persistent-data/stacks-blockchain:/root/stacks-node/data \ |
|||
-v $(pwd)/config:/src/stacks-node \ |
|||
-p 20443:20443 \ |
|||
-p 20444:20444 \ |
|||
blockstack/stacks-blockchain \ |
|||
/bin/stacks-node start --config /src/stacks-node/Config.toml |
|||
``` |
|||
|
|||
You can verify the running [`stacks-blockchain`][] container with the command: |
|||
|
|||
```sh |
|||
docker ps --filter name=stacks-blockchain |
|||
``` |
|||
|
|||
## Step 5: verifying the services |
|||
|
|||
You can now verify that each of the services is running and talking to the others. |
|||
|
|||
To verify the database is ready: |
|||
|
|||
1. Connect to the Postgres instance with the command `psql -h localhost -U postgres`. Use the password from the |
|||
`POSTGRES_PASSWORD` environment variable you set when running the container. |
|||
2. List current databases with the command `\l` |
|||
3. Disconnect from the database with the command `\q` |
|||
|
|||
To verify the [`stacks-blockchain`][] tip height is progressing use the following command: |
|||
|
|||
```sh |
|||
curl -sL localhost:20443/v2/info | jq |
|||
``` |
|||
|
|||
If the instance is running you should recieve terminal output similar to the following: |
|||
|
|||
```json |
|||
{ |
|||
"peer_version": 402653184, |
|||
"pox_consensus": "89d752034e73ed10d3b97e6bcf3cff53367b4166", |
|||
"burn_block_height": 666143, |
|||
"stable_pox_consensus": "707f26d9d0d1b4c62881a093c99f9232bc74e744", |
|||
"stable_burn_block_height": 666136, |
|||
"server_version": "stacks-node 2.0.11.1.0-rc1 (master:67dccdf, release build, linux [x86_64])", |
|||
"network_id": 1, |
|||
"parent_network_id": 3652501241, |
|||
"stacks_tip_height": 61, |
|||
"stacks_tip": "e08b2fe3dce36fd6d015c2a839c8eb0885cbe29119c1e2a581f75bc5814bce6f", |
|||
"stacks_tip_consensus_hash": "ad9f4cb6155a5b4f5dcb719d0f6bee043038bc63", |
|||
"genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", |
|||
"unanchored_tip": "74d172df8f8934b468c5b0af2efdefe938e9848772d69bcaeffcfe1d6c6ef041", |
|||
"unanchored_seq": 0, |
|||
"exit_at_block_height": null |
|||
} |
|||
``` |
|||
|
|||
Verify the [`stacks-blockchain-api`][] is receiving data from the [`stacks-blockchain`][] with the following command: |
|||
|
|||
```sh |
|||
curl -sL localhost:3999/v2/info | jq |
|||
``` |
|||
|
|||
If the instance is configured correctly, you should recieve terminal output similar to the following: |
|||
|
|||
```json |
|||
{ |
|||
"peer_version": 402653184, |
|||
"pox_consensus": "e472cadc17dcf3bc1afafc6aa595899e55f25b72", |
|||
"burn_block_height": 666144, |
|||
"stable_pox_consensus": "6a6fb0aa75a8acd4919f56c9c4c81ce5bc42cac1", |
|||
"stable_burn_block_height": 666137, |
|||
"server_version": "stacks-node 2.0.11.1.0-rc1 (master:67dccdf, release build, linux [x86_64])", |
|||
"network_id": 1, |
|||
"parent_network_id": 3652501241, |
|||
"stacks_tip_height": 61, |
|||
"stacks_tip": "e08b2fe3dce36fd6d015c2a839c8eb0885cbe29119c1e2a581f75bc5814bce6f", |
|||
"stacks_tip_consensus_hash": "ad9f4cb6155a5b4f5dcb719d0f6bee043038bc63", |
|||
"genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", |
|||
"unanchored_tip": "74d172df8f8934b468c5b0af2efdefe938e9848772d69bcaeffcfe1d6c6ef041", |
|||
"unanchored_seq": 0, |
|||
"exit_at_block_height": null |
|||
} |
|||
``` |
|||
|
|||
Once the API is running, you can use it to [interact with other API endpoints][`stacks-blockchain-api`]. |
|||
|
|||
## Stopping the API node |
|||
|
|||
As discussed previously, if you want to bring down your API node, you must stop the services in the reverse order that |
|||
you started them. Performing the shutdown in this order ensures that you don't lose any data while shutting down |
|||
the node. |
|||
|
|||
Use the following commands to stop the local API node: |
|||
|
|||
```sh |
|||
docker stop stacks-blockchain |
|||
docker stop stacks-blockchain-api |
|||
docker stop postgres |
|||
``` |
|||
|
|||
## Additional reading |
|||
|
|||
- [Running an API instance with Docker][] in the `stacks-blockchain-api` repo |
|||
- [Running an API instance from source][] in the `stacks-blockchain-api` repo |
|||
|
|||
[running an api instance with docker]: https://github.com/blockstack/stacks-blockchain-api/blob/master/running_an_api.md |
|||
[running an api instance from source]: https://github.com/blockstack/stacks-blockchain-api/blob/master/running_api_from_source.md |
|||
[`stacks-blockchain`]: https://github.com/blockstack/stacks-blockchain |
|||
[`stacks-blockchain-api`]: https://github.com/blockstack/stacks-blockchain-api |
|||
Loading…
Reference in new issue