From 5ca4f95c0616a29143e809c55fc2fd1a26698a94 Mon Sep 17 00:00:00 2001
From: wileyj <2847772+wileyj@users.noreply.github.com>
Date: Wed, 14 Jul 2021 17:38:26 -0400
Subject: [PATCH] keep testnet docs inline with mainnet

add links to each other here
---
 .../understand-stacks/running-mainnet-node.md |  12 +-
 .../understand-stacks/running-testnet-node.md | 303 +++++++-----------
 2 files changed, 128 insertions(+), 187 deletions(-)

diff --git a/src/pages/understand-stacks/running-mainnet-node.md b/src/pages/understand-stacks/running-mainnet-node.md
index d905fa46..d9cb9565 100644
--- a/src/pages/understand-stacks/running-mainnet-node.md
+++ b/src/pages/understand-stacks/running-mainnet-node.md
@@ -62,7 +62,7 @@ docker pull blockstack/stacks-blockchain
 Create a directory structure for the service data with the following command:
 
 ```sh
-mkdir -p ./stacks-node/{persistent-data/stacks-blockchain,config} && cd stacks-node
+mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node
 ```
 
 ## Step 2: running Stacks blockchain
@@ -100,8 +100,8 @@ Start the [`stacks-blockchain`][] container with the following command:
 ```sh
 docker run -d --rm \
   --name stacks-blockchain \
-  -v $(pwd)/persistent-data/stacks-blockchain:/root/stacks-node/data \
-  -v $(pwd)/config:/src/stacks-node \
+  -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \
+  -v $(pwd)/config/mainnet:/src/stacks-node \
   -p 20443:20443 \
   -p 20444:20444 \
   blockstack/stacks-blockchain \
@@ -171,6 +171,6 @@ docker stop stacks-blockchain
 ## Additional reading
 
 - [Running an API instance with Docker][]
-
-[running an api instance with docker]: /understand-stacks/running-api-node
-[`stacks-blockchain`]: https://github.com/blockstack/stacks-blockchain
+  [running a testnet node with docker]: /understand-stacks/running-testnet-node
+  [running an api instance with docker]: /understand-stacks/running-api-node
+  [`stacks-blockchain`]: https://github.com/blockstack/stacks-blockchain
diff --git a/src/pages/understand-stacks/running-testnet-node.md b/src/pages/understand-stacks/running-testnet-node.md
index 4fd65bbc..1c82c609 100644
--- a/src/pages/understand-stacks/running-testnet-node.md
+++ b/src/pages/understand-stacks/running-testnet-node.md
@@ -1,6 +1,6 @@
 ---
 title: Running a testnet node
-description: Learn how to set up and run a testnet node
+description: Set up and run a testnet node with Docker
 icon: TestnetIcon
 duration: 15 minutes
 experience: beginners
@@ -13,239 +13,180 @@ images:
 
 ## Introduction
 
-This tutorial will walk you through the following steps:
+This procedure demonstrates how to run a local testnet node using Docker images.
 
-- Download and install the node software
-- Run the node against testnet
-- Mine Stacks token
+-> This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on
+Windows.
 
-## Requirements
+## Prerequisites
 
-In order to run a node, some software and hardware requirements need to be considered.
+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:
 
-### Hardware
+- [Docker](https://docs.docker.com/get-docker/)
+- [curl](https://curl.se/download.html)
+- [jq](https://stedolan.github.io/jq/download/)
 
-Running a node has no specialized hardware requirements. People were successful at running a node on Raspberry Pis, for instance.
-Minimum requirements are moving targets due to the nature of the project and some factors should be considered:
+### Firewall configuration
 
-- compiling node sources locally requires computing and storage resources
-- as the chain grows, the on-disk state will grow over time
+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.
 
-With these considerations in mind, we suggest hardware based on a general-purpose specification, similarly to [GCP E2 machine standard 2](https://cloud.google.com/compute/docs/machine-types#general_purpose) or [AWS EC2 t3.large standard](https://aws.amazon.com/ec2/instance-types/):
+The following ports must open on the host machine:
 
-- 2 vCPUs
-- 8 GB memory
-- ~50-GB disk (preferably SSDs)
+Ingress:
 
-It is also recommended to run the node with a publicly routable IP, that way other peers in the network will be able to connect to it.
+- stacks-blockchain (open to `0.0.0.0/0`):
+  - `20443 TCP`
+  - `20444 TCP`
 
-### Software
+Egress:
 
-If you use Linux, you may need to manually install [`libssl-dev`](https://wiki.openssl.org/index.php/Libssl_API) and other packages. In your command line, run the following to get all packages:
+- `18332`
+- `18333`
+- `20443-20444`
 
-```bash
-sudo apt-get install build-essential cmake libssl-dev pkg-config
-```
-
-Ensure that you have Rust installed. If you are using macOS, Linux, or another Unix-like OS, run the following. If you are on a different OS, follow the [official Rust installation guide](https://www.rust-lang.org/tools/install).
-
-```bash
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
-```
-
-In case you just installed Rust, you will be prompted to run the following command to make the `cargo` command available:
-
-```bash
-source $HOME/.cargo/env
-```
-
-## Installing the node from pre-built binary
-
-### Step 1: Get the distributable
-
-Download and unzip the distributable which cooresponds to your environment [from the latest release](https://github.com/blockstack/stacks-blockchain/releases/latest).
-
-If you're running on Windows, [please follow our instructions from installing a node on Windows.](#running-the-testnet-node-on-windows)
-
-### Step 2: Run the binary
-
-To run the `stacks-node` binary, execute the following:
+These egress ports are for syncing [`stacks-blockchain`][] and Bitcoin headers. If they're not open, the sync will fail.
 
-```bash
-./stacks-node xenon
-```
-
-**Awesome. Your node is now connected to the testnet network.**
-
-Your node will receive new blocks when they are produced, and you can use the [Stacks Node RPC API](/understand-stacks/stacks-blockchain-api#proxied-stacks-node-rpc-api-endpoints) to send transactions, fetch information for contracts and accounts, and more.
-
-## Installing the node from source
+## Step 1: initial setup
 
-You might want to build and install from source if there are some updates in the [main branch](https://github.com/blockstack/stacks-blockchain) which aren't yet released, or if there is no pre-built binary for your environment.
+In order to run the testnet 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:
 
-### Step 1: Install the node
-
-Clone this repository:
-
-```bash
-git clone https://github.com/blockstack/stacks-blockchain.git; cd stacks-blockchain
+```sh
+docker pull blockstack/stacks-blockchain
 ```
 
-Change the below values to reflect the version, branch, and git commit of the source code being built for accuracy:
+Create a directory structure for the service data with the following command:
 
-```bash
-# The following values are just an example
-export STACKS_NODE_VERSION=2.0.9
-export GIT_BRANCH=master
-export GIT_COMMIT=e7f178b
+```sh
+mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/testnet,config/testnet} && cd stacks-node
 ```
 
-Install the Stacks node by running:
+## Step 2: running Stacks blockchain
 
-```bash
-cargo build --workspace --release --bin stacks-node
-# binary will be in target/release/stacks-node
-```
+First, create the `./config/Config.toml` file and add the following content to the
+file using a text editor:
 
-To install Stacks node with extra debugging symbols, run:
+```toml
+[node]
+working_dir = "/root/stacks-node/data"
+rpc_bind = "0.0.0.0:20443"
+p2p_bind = "0.0.0.0:20444"
+bootstrap_node="047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.stacks.co:20444"
+wait_time_for_microblocks = 10000
 
-```bash
-cargo build --workspace --bin stacks-node
-# binary will be in target/debug/stacks-node
-```
+[burnchain]
+chain = "bitcoin"
+mode = "xenon"
+peer_host = "bitcoin.testnet.blockstack.com"
+username = "blockstack"
+password = "blockstacksystem"
+rpc_port = 18332
+peer_port = 18333
 
--> This process will take a few minutes to complete
+[[ustx_balance]]
+address = "ST2QKZ4FKHAH1NQKYKYAYZPY440FEPK7GZ1R5HBP2"
+amount = 10000000000000000
 
-### Step 2: Run the node
+[[ustx_balance]]
+address = "ST319CF5WV77KYR1H3GT0GZ7B8Q4AQPY42ETP1VPF"
+amount = 10000000000000000
 
-You're all set to run a node that connects to the testnet network.
+[[ustx_balance]]
+address = "ST221Z6TDTC5E0BYR2V624Q2ST6R0Q71T78WTAX6H"
+amount = 10000000000000000
 
-If installed without debugging symbols, run:
+[[ustx_balance]]
+address = "ST2TFVBMRPS5SSNP98DQKQ5JNB2B6NZM91C4K3P7B"
+amount = 10000000000000000
 
-```bash
-target/release/stacks-node xenon
+[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
 ```
 
-If installed with debugging symbols, run:
+Start the [`stacks-blockchain`][] container with the following command:
 
-```bash
-target/debug/stacks-node xenon
+```sh
+docker run -d --rm \
+  --name stacks-blockchain \
+  -v $(pwd)/persistent-data/stacks-blockchain/testnet:/root/stacks-node/data \
+  -v $(pwd)/config/testnet:/src/stacks-node \
+  -p 20443:20443 \
+  -p 20444:20444 \
+  blockstack/stacks-blockchain \
+/bin/stacks-node start --config /src/stacks-node/Config.toml
 ```
 
-The first time you run this, you'll see some logs indicating that the Rust code is being compiled. Once that's done, you should see some logs that look something like the this:
+You can verify the running [`stacks-blockchain`][] container with the command:
 
-```bash
-INFO [1588108047.585] [src/chainstate/stacks/index/marf.rs:732] First-ever block 0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206
+```sh
+docker ps --filter name=stacks-blockchain
 ```
 
-## Running the testnet node on Windows
-
-### Prerequisites
-
-Before you begin, check that you have the below necessary softwares installed on your PC
+## Step 3: verifying the services
 
-- [Microsoft C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/).
+_Note: the initial burnchain header sync can take several minutes, until this is done the following commands will not work_
 
--> **Tip**: While installing the Microsoft Visual Studio Build tools using the above link, select the C++ Build tools option when prompted.
-![C++ Build Tools](/images/C++BuildTools.png)
+To verify the [`stacks-blockchain`][] burnchain header sync progress:
 
-- [NodeJs](https://nodejs.org/en/download/).
-- [Git](https://git-scm.com/downloads).
-
-#### Optional Dependencies
-
-- [Python](https://www.python.org/downloads/).
-- [Rust](https://www.rust-lang.org/tools/install).
-
-### Download the Binary and run the follower node
-
--> **Note**: Please make sure to download the new Binary and follow the below steps as and when a [new release build](https://github.com/blockstack/stacks-blockchain/releases/latest) is available.
-
-First, Visit the [Stacks Github releases repo](https://github.com/blockstack/stacks-blockchain/releases/latest). From the various binary list, click to download the Windows binary. Refer the image below.
-![BinaryList](/images/mining-windows.png)
-
-Next, click on save file and Press **Ok** in the popup window.
-![Windowspopup](/images/mining-windows-popup.png)
-
-Once saved, Extract the binary. Open the command prompt **from the folder where binary is extracted** and execute the below command:
-
-```bash
-stacks-node xenon
-# This command will start the testnet follower node.
+```sh
+docker logs stacks-blockchain
 ```
 
--> **Note** : While starting the node for the first time, windows defender will pop up with a message to allow access. If so, allow access to run the node.
-![Windows Defender](/images/windows-defender.png)
-
-To execute Stacks node with extra debugging enabled, run:
+The output should be similar to the following:
 
-```bash
-set RUST_BACKTRACE=full
-set STACKS_LOG_DEBUG=1
-stacks-node xenon
-# This command will execute the binary and start the follower node with debug enabled.
 ```
-
-The first time you run this, you'll see some logs indicating that the Rust code is being compiled. Once that's done, you should see some logs that look something like the this:
-
-```bash
-INFO [1588108047.585] [src/chainstate/stacks/index/marf.rs:732] First-ever block 0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206
+INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 2034380)
+INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 2034380)
+INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 2034380)
 ```
 
-**Awesome. Your node is now connected to the testnet network.**
-
-## Optional: Running with Docker
-
-Alternatively, you can run the testnet node with Docker.
+To verify the [`stacks-blockchain`][] tip height is progressing use the following command:
 
--> Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine.
-
-```bash
-docker run -d \
-  --name stacks_follower \
-  -p 20443:20443 \
-  -p 20444:20444 \
-  blockstack/stacks-blockchain \
-  stacks-node xenon
+```sh
+curl -sL localhost:20443/v2/info | jq
 ```
 
--> To enable debug logging, add the ENV VARS `RUST_BACKTRACE="full"` and `STACKS_LOG_DEBUG="1"`.
+If the instance is running you should recieve terminal output similar to the following:
 
-You can review the node logs with this command:
-
-```bash
-docker logs -f stacks_follower
+```json
+{
+  "peer_version": 4207599105,
+  "pox_consensus": "12f7fa85e5099755a00b7eaecded1aa27af61748",
+  "burn_block_height": 2034380,
+  "stable_pox_consensus": "5cc4e0403ff6a1a4bd17dae9600c7c13d0b10bdf",
+  "stable_burn_block_height": 2034373,
+  "server_version": "stacks-node 2.0.11.2.0-rc1 (develop:7b6d3ee+, release build, linux [x86_64])",
+  "network_id": 2147483648,
+  "parent_network_id": 118034699,
+  "stacks_tip_height": 509,
+  "stacks_tip": "e0ee952e9891709d196080ca638ad07e6146d4c362e6afe4bb46f42d5fe584e8",
+  "stacks_tip_consensus_hash": "12f7fa85e5099755a00b7eaecded1aa27af61748",
+  "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b",
+  "unanchored_tip": "32bc86590f11504f17904ee7f5cb05bcf71a68a35f0bb3bc2d31aca726090842",
+  "unanchored_seq": 0,
+  "exit_at_block_height": null
+}
 ```
 
-## Optional: Running in Kubernetes with Helm
-
-In addition, you're also able to run a testnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/blockstack/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain).
-
-Ensure you have the following prerequisites installed on your machine:
+## Stopping the testnet node
 
-- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster)
-- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
-- [helm](https://helm.sh/docs/intro/install/)
+Use the following commands to stop the local testnet node:
 
-To install the chart with the release name `my-release` and run the node as a follower:
-
-```bash
-minikube start # Only run this if standing up a local Kubernetes cluster
-helm repo add blockstack https://charts.blockstack.xyz
-helm install my-release blockstack/stacks-blockchain
-```
-
-You can review the node logs with this command:
-
-```bash
-kubectl logs -l app.kubernetes.io/name=stacks-blockchain
+```sh
+docker stop stacks-blockchain
 ```
 
-For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/blockstack/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain).
-
-## Optional: Mining Stacks token
-
-Now that you have a running testnet node, you can easily set up a miner.
+## Additional reading
 
-[@page-reference | inline]
-| /start-mining/testnet
+- [Running an API instance with Docker][]
+  [running a mainnet node with docker]: /understand-stacks/running-mainnet-node
+  [running an api instance with docker]: /understand-stacks/running-api-node
+  [`stacks-blockchain`]: https://github.com/blockstack/stacks-blockchain