Update Core Node Admin Guide (stellar#376)

* update the installation instructions to be more like the gh docs * use the high-level overview from the github pages in the README * update hardware and network requirements * better punctuation * initial pass at updating the core node admin guide work still needs to be done surrounding the `configuring.mdx` file in particular, as well as the overall structure of this section * bring Soroban Settings doc into the admin guide from gh * markdown linting * reword a link in soroban-settings * use a bulleted list instead of numbered list * remove most (out-of-date-anyway) commands from `commands.mdx` * update "node setup process" in README.mdx * another pass at shuffling some config/prereq/prep stuff around * rough draft of core node admin guide update complete. ready for review * update hardware requirements * Update network/core-node/README.mdx Co-authored-by: Justin Rice <[email protected]> * Update network/core-node/README.mdx Co-authored-by: Justin Rice <[email protected]> * fix link definition to SEP-20 case for consistency * change link back to the original * add a note about "data retrieval" node types, along with links * remove another mention of archiver node types * remove small note about horizon reingesting data from core * add a note recommending against storing metadata for all history * remove another mention of "archiver nodes" * remove the main description of archiver nodes in the top-level README * remove more archiver node language, clean up duplicate points * alert people that quickstart is not for production * Update network/core-node/admin-guide/maintenance.mdx Co-authored-by: Justin Rice <[email protected]> * Update network/core-node/admin-guide/network-upgrades.mdx Co-authored-by: Justin Rice <[email protected]> * Update network/core-node/admin-guide/soroban-settings.mdx Co-authored-by: Justin Rice <[email protected]> * Update network/core-node/admin-guide/network-upgrades.mdx Co-authored-by: Justin Rice <[email protected]> * add more "human" reasons our upgrades are so orchestrated * remove note about having 1TB "on hand" * remove another "archive node" mention * refine some language around caching and history archives * Update network/core-node/admin-guide/publishing-history-archives.mdx Co-authored-by: Justin Rice <[email protected]> * move installation instructions for stellar-archivist to a more sensible place * fix a couple Alert imports * add link to types of node on main intro page * add a link/note about partitions in `ll` command * update command outputs in monitoring.mdx * re-arrange installation methods, add some context and recommendations * add example for updated history archives * add note about stellarbeat to monitoring.mdx * some slight tweaks to hardware/storage prerequisites * some re-wording of state catchup and history archives language --------- Co-authored-by: Justin Rice <[email protected]>
philipliu · Apr 24, 2024 · 50e2602 · 50e2602
1 parent 0aa9316
commit 50e2602
Show file tree

Hide file tree

Showing 17 changed files with 1,110 additions and 677 deletions.
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -360,6 +360,8 @@ const config = {
  "docker",
  "kotlin",
  "dart",
+ "nginx",
+ "log",
  "powershell"
  ],
  },

diff --git a/network/core-node/README.mdx b/network/core-node/README.mdx
@@ -15,15 +15,30 @@ If you’re serious about building on Stellar, have a production-level product o
 
 If you’re going the DIY route, this section of the docs is for you. It explains the technical and operational aspects of installing, configuring, and maintaining a Stellar Core node, and should help you figure out the best way to set up your Stellar integration.
 
-The basic flow, which you can navigate through using the menu on the left, goes like this:
+## Node Setup Process
 
-- Choose which type of node you want to run
-- Prepare Your Environment
-- Install Stellar Core
-- Configure Stellar Core
-- Join the network
-- Monitor and maintain your node
-- Join the validators channels to stay on top of critical upgrades and network votes
+The basic flow, which you can navigate through using the "Admin Guide" on the left, goes (roughly) like this:
+
+### Initial Setup
+
+1. Use the information on this _Introduction_ page to determine which [type of node](#types-of-nodes) you want to run.
+2. [Prerequisite](./admin-guide/prerequisites.mdx) software must be installed (and configured according to your needs).
+3. [Install](./admin-guide/installation.mdx) the Stellar Core software on your instance.
+4. [Configure](./admin-guide/configuring.mdx) the Stellar Core software to suit your needs and environment.
+5. [Prepare](./admin-guide/environment-preparation.mdx) your node instance and environment. This includes the optional step of setting your node up to [publish history archives](./admin-guide/publishing-history-archives.mdx) of the ledger.
+6. [Start your node](./admin-guide/running-node.mdx) and join the network.
+7. [Logging](./admin-guide/logging.mdx) and [monitoring](./admin-guide/monitoring.mdx) should be appropriately set up and used to meet your needs.
+
+### Ongoing Requirements
+
+8. [Maintenance](./admin-guide/maintenance.mdx) is required from time to time to keep your node up-to-date and participating in the network.
+9. [Network upgrades](./admin-guide/network-upgrades.mdx) require validator consensus, and you will need to consider casting a vote in the event of a protocol upgrade.
+10. [Soroban settings](./admin-guide/soroban-settings.mdx) are network-wide, configurable, and changes can be proposed by anyone. Similar to protocol upgrades, changes to these settings will require validator consensus, so you should be prepared to participate.
+
+### Other Information
+
+- Stellar Core uses a robust [command line](./admin-guide/commands.mdx) tool to control and operate a node. We've gathered information on some of the most-used commands, and linked to further, more comprehensive cli documentation.
+- We've collected some miscellaneous helpful and [advanced](./admin-guide/advanced.mdx) information that could be useful as you understand and implement your core node.
 
 ## Types of nodes
 
@@ -40,7 +55,11 @@ To make things easier, we’ll define three types of nodes based on permutations
 | --- | --- | --- | --- | --- |
 | **Basic Validator** | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | |
 | **Full Validator** | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: | :heavy_check_mark: |
-| **Archiver** | :heavy_check_mark: | :heavy_check_mark: | | :heavy_check_mark: |
+
+Additionally, there are two varieties of _non-validating_ nodes that can be used for data access and transaction submission. Each of these has its own process for setting up, maintaining, etc., and relevant links are provided below.
+
+1. [**Horizon Nodes**](../horizon/README.mdx) can be used for submitting transactions, as well as exposing a REST API service to query and retrieve network state.
+2. [**Soroban RPC Nodes**](../soroban-rpc/README.mdx) can be used for simulating and/or submitting transactions, as well as exposing an RPC service to query and retrieve current network state.
 
 <Alert>
 
@@ -66,20 +85,10 @@ The advantage: signatures can serve as official endorsements of specific ledgers
 
 #### Validating, offers public archive
 
-A Full Validator is the same as a Basic Validator except that it also publishes a [History Archive](./admin-guide/publishing-history-archives.mdx) containing snapshots of the ledger, including all transactions and their results. A Full Validator writes to an internet-facing blob store — such as AWS or Azure — so it's a bit more expensive and complex to run, but it also does the most to support the network’s resilience and decentralization.
+A Full Validator is the same as a Basic Validator except that it also publishes a [History Archive](./admin-guide/environment-preparation.mdx) containing snapshots of the ledger, including all transactions and their results. A Full Validator writes to an internet-facing blob store — such as AWS or Azure — so it's a bit more expensive and complex to run, but it also does the most to support the network’s resilience and decentralization.
 
 When other nodes join the network — or experience difficulty and temporarily fall out of sync — they can consult archives offered by Full Validators to catch up on the history of the network. Redundant archives prevent a single point of failure, and allow network participants to verify the veracity of a given history.
 
 Generally, organizations that run Full Validators don't use them to query network data or submit transactions. Most of those organizations are also part of — or on track to join — [Tier 1](./tier-1-orgs.mdx), which is a core group of network participants who run three Full Validators to contribute maximum redundancy.
 
 **Use a Full Validator to sign off on transactions and to contribute to the health and decentralization of the network.**
-
-### Archiver
-
-#### Non-validating, offers public archive
-
-An Archiver is a rare bird: like a Full Validator, it publishes the activity of the network in long-term storage; unlike a Full Validator, it does not participate in consensus.
-
-Archivers help with decentralization a bit by offering redundant accounts of the network’s history, but they don’t vote or sign ledgers, so their usefulness is fairly limited. If you run a Stellar-facing service, like a blockchain explorer, you may want to run one. Otherwise, you’re probably better off choosing one of the other two types.
-
-**Use an archiver if you want to referee the network. Which is unlikely.**
diff --git a/network/core-node/admin-guide/README.mdx b/network/core-node/admin-guide/README.mdx
@@ -5,6 +5,8 @@ sidebar_position: 20
 
 import DocCardList from "@theme/DocCardList";
 
-All you need to know about setting up, running, and using a core validator node.
+Stellar Core is the program nodes use to communicate with other nodes to create and maintain the Stellar peer-to-peer network. It's an implementation of the Stellar Consensus Protocol configured to construct a chain of ledgers guaranteed to be in agreement across all participating nodes at all times.
+
+These pages describe various aspects of installing, configuring, and maintaining a `stellar-core` node.
 
 <DocCardList />
diff --git a/network/core-node/admin-guide/advanced.mdx b/network/core-node/admin-guide/advanced.mdx
@@ -0,0 +1,27 @@
+---
+title: Advanced
+sidebar_position: 130
+---
+
+This page contains information that is useful to know but that should not stop somebody from running a node.
+
+## Creating Your Own Private Network
+
+The [stellar-core GitHub repository] holds [a `testnet.md` file] which contains a short tutorial demonstrating how to configure and run a short-lived, isolated test network.
+
+## Runtime Information: Start and Stop
+
+Stellar-core can be started directly from the command line, or through a supervision system such as `init`, `upstart`, or `systemd`.
+
+Stellar-core can be gracefully exited at any time by delivering `SIGINT` or pressing `CTRL-C`. It can be safely, forcibly terminated with `SIGTERM` or `SIGKILL`. The latter may leave a stale lock file in the `BUCKET_DIR_PATH`, and you may need to remove this file before stellar-core will restart. Broadly speaking, all components are designed to recover from abrupt termination.
+
+Stellar-core can also be packaged in a container system such as Docker, so long as `BUCKET_DIR_PATH` and the database are stored on persistent volumes. For an example, see [`stellar/quickstart`].
+
+## In-depth Architecture
+
+The [stellar-core GitHub repository] also contains [the `architecture.md` file], which describes how stellar-core is structured internally, how it is intended to be deployed, and the collection of servers and services needed to get the full functionality and performance.
+
+[stellar-core github repository]: https:/stellar/stellar-core
+[a `testnet.md` file]: https:/stellar/stellar-core/blob/master/docs/software/testnet.md
+[`stellar/quickstart`]: https:/stellar/quickstart
+[the `architecture.md` file]: https:/stellar/stellar-core/blob/master/docs/architecture.md