Book edits (#2597)

* simplify beacon node quickstart

* remove extra emacs generated file

* focus sync info around slot start message

* sync edits

* log rotate edits + clarifications

* remove validator keys folder

docs/the_nimbus_book/src/SUMMARY.md

@@ -2,10 +2,13 @@
 - [Introduction](./intro.md)
 - [Design goals](./philosophy.md)
 - [System requirements](./hardware.md)
-- [Run the beacon node (quickstart)](./quick-start.md)
-- [Run a validator](./run-a-validator.md)
 - [Mainnet checklist](./preparation.md)
 
+# Quickstart
+- [Run the beacon node](./quick-start.md)
+- [Run a validator](./run-a-validator.md)
+
+
 # How-to (beacon node)
 - [Install dependencies](./install.md)
 - [Build the beacon node](./build.md)

docs/the_nimbus_book/src/beacon-node-systemd.md

@@ -65,7 +65,7 @@ sudo systemctl enable nimbus-eth2-prater --now
 sudo journalctl -u nimbus-eth2-prater.service
 ```
 
-This will show you the Nimbus logs at the default setting -- it should include regular "slot start" messages which will show your sync progress.
+This will show you the Nimbus logs at the default setting -- it should include regular "slot start" messages which will show your [sync progress](./keep-an-eye.md#keep-track-of-your-syncing-progress).
 
 For more options, see [here](https://www.raspberrypi.org/documentation/linux/usage/systemd.md).
 

docs/the_nimbus_book/src/binaries.md

@@ -14,3 +14,5 @@ We've designed the build process to be reproducible. In practice, this means tha
 
 For instructions on how to reproduce the build, [see here](https://github.com/status-im/nimbus-eth2/blob/master/docker/dist/README.md#reproducing-the-build).
 
+> **N.B.** Binaries are built with Docker. As such they do not support the `log-file` [option](./options.md). We recommend capturing the console output with a [log rotation helper](./log-rotate.md) instead. 
+

docs/the_nimbus_book/src/build.md

@@ -1,11 +1,5 @@
 # Build the beacon node
 
-The beacon node connects to the eth2 network, manages the blockchain, and provides API's to interact with the beacon chain.
-
-Importantly, you need to have built the beacon node in order to be able to import your keys.
-
-*Todo: explain relationship between beacon node and validator client*
-
 ## Prerequisites
 
 Before building and running the application, make sure you've gone through the [installed the required dependencies](./install.md).
@@ -27,7 +21,4 @@ To build the Nimbus beacon node and it's dependencies, run:
 make nimbus_beacon_node
 ```
 
-## Updating the node
-
-Make sure you stay on the lookout for any critical updates to Nimbus and [keep your node updated](./keep-updated.md).
 

docs/the_nimbus_book/src/docker.md

@@ -8,6 +8,9 @@ These images are simply the contents of [release tarballs](./binaries.md) inside
 
 The unpacked archive is in `/home/user/nimbus-eth2` which is also the default *WORKDIR*. The default *ENTRYPOINT* is the binary itself: `/home/user/nimbus-eth2/build/nimbus\_beacon\_node`
 
+> **N.B.** Docker images do not support the `log-file` [option](./options.md) - The way we recommend setting up docker is to capture its console output with a [log rotation helper](./log-rotate.md).
+
+
 ## Usage
 
 You need to create an external data directory and mount it as a volume inside the container, with  mounting point: `/home/user/nimbus-eth2/build/data`
@@ -35,3 +38,4 @@ docker-compose -f docker-compose-example1.yml up --quiet-pull --no-color --detac
 ```
 
 > **Note:** The rather voluminous logging is done on `stdout`, so you might want to change the system-wide Docker logging defaults (which dumps everything in `/var/lib/docker/containers/CONTAINER_ID/CONTAINER_ID-json.log`) to something like `syslog`. We recommend using a log rotation system with appropriate intervals for logs of this size.
+

docs/the_nimbus_book/src/keep-an-eye.md

@@ -31,18 +31,24 @@ Note that the port number is displayed directly after the IP -- in the above cas
 
 ## Keep track of your syncing progress
 
-To keep track of your syncing progress, have a look at the output at the very bottom of the terminal window in which your validator is running. You should see something like:
+To keep track of your sync progress, pay attention to the `Slot start` messages in you logs:
 
 ```
-peers: 35 ❯ finalized: ada7228a:8765 ❯ head: b2fe11cd:8767:2 ❯ time: 9900:7 (316807) ❯ sync: wPwwwwwDwwDPwPPPwwww:7:4.2313:4.0627:03h01m(280512)
+INF 2021-05-24 14:53:59.067+02:00 Slot start                                 
+topics="beacnde" tid=3485464 file=nimbus_beacon_node.nim:968 lastSlot=1253067 wallSlot=1253068 delay=67ms515us0ns
+peers=22
+head=eb994064:90753 
+headEpoch=2836 
+finalized=031b9591:90688 
+finalizedEpoch=2834 
+sync="PPPPPDDDDP:10:15.4923:7.7398:01d17h43m (90724)"
 ```
 
 Where:
 - `peers` tells you how many peers you're currently connected to (in the above case, 35 peers)
 - `finalized` tells you the most recent finalized epoch you've synced to so far (the 8765th epoch)
 - `head` tells you the most recent slot you've synced to so far (the 2nd slot of the 8767th epoch)
-- `time` tells you the current time since Genesis (the 7th slot of the 9900th epoch -- or equivalently, the 316,807th slot)
+- `sync` tells you how fast you're syncing right now (`15.4923` blocks per second), your average sync speed since you stared (`7.7398` blocks per second), the time left until you're fully synced (`01d17h43m`) how many blocks you've synced so far (`90724`), along with information about 10 sync workers linked to the 10 most performant peers you are currently connected to (represented by a string of letters and a number).
-- `sync` tells you how fast you're syncing right now (4.2313 blocks per second), your average sync speed since you stared (4.0627 blocks per second), the time left until you're fully synced (3 hours and 1 min) how many blocks you've synced so far (280,512), along with information about 20 sync workers linked to the 20 most performant peers you are currently connected to (represented by a string of letters and a number).
 
 The string of letters -- what we call the `sync worker map` (in the above case represented by `wPwwwwwDwwDPwPPPwwww`) represents the status of the sync workers mentioned above, where:
 
@@ -55,8 +61,8 @@ The string of letters -- what we call the `sync worker map` (in the above case r
     U - updating peer's status information
 ```
 
-The number following it (in the above case represented by `7`) represents the number of workers that are currently active (i.e not sleeping or waiting for a peer).
+The number following it (in the above case represented by `10`) represents the number of workers that are currently active (i.e not sleeping or waiting for a peer).
 
-> **Note:** If you're running Nimbus as a service, the above status bar won't be visible to you. You can use you the RPC calls outlined in the [API page](./api.md) to retrieve similar information.
+> **Note:** You can also use you the RPC calls outlined in the [API page](./api.md) to retrieve similar information.
 
 

docs/the_nimbus_book/src/log-rotate.md

@@ -2,7 +2,7 @@
 
 Nimbus logs are written to stdout, and optionally to a file. Writing to a file for a long-running process may lead to difficulties when the file grows large. This is typically solved with a *log rotator*. A log rotator is responsible for switching the written-to file, as well as compressing and removing old logs.
 
-## Using "logrotate"
+## Using `logrotate`
 
 [logrotate](https://github.com/logrotate/logrotate) provides log rotation and compression. The corresponding package will install its Cron hooks (or Systemd timer) -- all you have to do is add a configuration file for Nimbus-eth2 in "/etc/logrotate.d/nimbus-eth2":
 
@@ -27,7 +27,7 @@ daily
 rotate 7
 ```
 
-## Using "rotatelogs"
+## Using `rotatelogs`
 
 [rotatelogs](https://httpd.apache.org/docs/2.4/programs/rotatelogs.html) is available on most servers and can be used with `Docker`, `Systemd` and manual setups to write rotated logs files.
 

docs/the_nimbus_book/src/migration.md

@@ -3,10 +3,10 @@
 
 *See [here](./migration-options.md) for advanced options*
 
-## Step 1 - Sync the Nimbus beacon node
+## Step 1 - Sync the beacon node
-No matter which client you are migrating over from, the first step is to sync the beacon node.
+No matter which client you are migrating over from, the first step is to sync the Nimbus beacon node.
 
-The easiest way to do this is to follow the [Nimbus quickstart guide](./quick-start.md).  Syncing the beacon node might take up to 30h depending on your hardware, so you should keep validating using your current setup until it completes.
+The easiest way to do this is to follow the [beacon node quick start guide](./quick-start.md).  Syncing the beacon node might take up to 30h depending on your hardware - you should keep validating using your current setup until it completes.
 
 
 ## Step 2 - Export your slashing protection history

docs/the_nimbus_book/src/quick-start.md

@@ -1,86 +1,25 @@
-# Run the beacon node (quickstart)
+# Run the beacon node
 
 This page takes you through how to run just the beacon node **without a validator attached.**
 
-Running a beacon node without a validator attached can help improve the anonymity properties of the network as a whole. 
+The beacon node connects to the eth2 network, manages the blockchain, and provides API's to interact with the beacon chain.
+
+Running a beacon node without a validator attached is a [worthwhile endeavor](https://vitalik.ca/general/2021/05/23/scaling.html#its-crucial-for-blockchain-decentralization-for-regular-users-to-be-able-to-run-a-node).
 
 It's also a necessary step to running a validator (since an active validator requires a synced beacon node).
 
-## 1. Install dependencies
+## 1. Install
 
-You'll need to install some packages in order for Nimbus to run correctly.
+[Install Nimbus' dependencies](./install.html#external-dependencies) 
-
-**Linux**
-
-On common Linux distributions the dependencies can be installed with
-
-```sh
-# Debian and Ubuntu
-sudo apt-get install build-essential git
-
-# Fedora
-dnf install @development-tools
-
-# Archlinux, using an AUR manager
-yourAURmanager -S base-devel
-```
-
-**macOS**
-
-Assuming you use [Homebrew](https://brew.sh/) to manage packages:
-
-```sh
-brew install cmake
-```
 
 
-## 2. Clone the Nimbus repository
 
-Run the following command to clone the [nimbus-eth2 repository](https://github.com/status-im/nimbus-eth2):
+## 2. Build
 
-```
+[Build the beacon node](./build.md) 
-git clone https://github.com/status-im/nimbus-eth2
-```
 
-## 3. Build the beacon node
 
-Change into the directory and build the beacon node.
-```
-cd nimbus-eth2
-make nimbus_beacon_node
-```
 
-*Patience... this may take a few minutes.*
+## 3. Sync
 
-## 4. Connect to the network
+[Sync the chain](./start-syncing.md)
-
-To connect to mainnet, run:
-```
-./run-mainnet-beacon-node.sh
-```
-
-To connect to the testnet , run:
-
-```
-./run-prater-beacon-node.sh
-```
-
-In both case you'll be prompted to enter a web3-provider url:
-
-```
-To monitor the Eth1 validator deposit contract, you'll need to pair
-the Nimbus beacon node with a Web3 provider capable of serving Eth1
-event logs. This could be a locally running Eth1 client such as Geth
-or a cloud service such as Infura. For more information please see
-our setup guide:
-
-https://status-im.github.io/nimbus-eth2/eth1.html
-
-Please enter a Web3 provider URL:
-```
-
-Press enter to skip (this is only important when you're running a validator).
-
-## 5. Keep track of your sync progress
-
-See [here](./keep-an-eye.html#keep-track-of-your-syncing-progress) for how to keep track of your sync progress.

docs/the_nimbus_book/src/start-syncing.md

@@ -57,3 +57,6 @@ To see a list of the command line options availabe to you, with descriptions, na
 ```
 ./nimbus_beacon_node --help
 ```
+### Keep track of your sync progress
+
+See [here](./keep-an-eye.html#keep-track-of-your-syncing-progress) for how to keep track of your sync progress.