Merge pull request #2677 from aeternity/docs

Better looking docs
aeternity · Aug 21, 2019 · 9506e5e · 9506e5e
2 parents 2725401 + db432bc
commit 9506e5e
Show file tree

Hide file tree

Showing 12 changed files with 168 additions and 126 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,17 @@
+# Welcome to Aeternity node documentation
+
+The documentation describes how to install, configure and operate an aeternity node.
+One can install it from a package, run a docker image or build it themselves.
+There is also additional documentation on mining with CUDA and build and/or join a Stratum pool.
+
+## Index
+
+- [Installation](installation.md)
+- [Configuration](configuration.md)
+- [Operation](operation.md)
+- [Docker](docker.md)
+- [Build from source](build.md)
+- [Build from source (Windows)](build-windows.md)
+- [CUDA Miner](cuda-miner.md)
+- [Stratum](stratum.md)
+- [Network Monitoring](monitoring.md)
diff --git a/docs/build-windows.md b/docs/build-windows.md
@@ -1,4 +1,4 @@
-# Build from source
+# Introduction
 
 This document describes how to build an Aeternity node from source on Windows using
 [MSYS2][msys2].

diff --git a/docs/build.md b/docs/build.md
@@ -1,9 +1,9 @@
-# Build from source
+# Introduction
 
 This document describes how to build an Aeternity node from source on current Ubuntu 16.04.4 LTS, Ubuntu 18.04 LTS and MacOS (latest).
 The commands below assume you are logged in with `sudo` user.
 
-## Dependencies installation
+## Dependencies
 
 ### Ubuntu
 #### Common tools and libraries
@@ -86,7 +86,7 @@ brew install autoconf
 
 For more details read the [dedicated Libsodium documentation](https://download.libsodium.org/doc/installation/).
 
-## Builds
+## Building
 
 The source code of the Aeternity node can be obtained by cloning the public [GitHub repository](https://github.com/aeternity/aeternity):
 

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -1,4 +1,4 @@
-# Configure an Aeternity node installed using a release binary
+# Introduction
 
 This document describes how to configure your Aeternity node installed using a release binary for joining a public network of nodes (e.g. testnet) knowing an initial network peer to join.
 
@@ -10,6 +10,7 @@ The `aeternity` system supports user-provided parameters via a JSON- or YAML-for
 The format of the config file is determined from the file extension: `.json` for JSON, or `.yaml` for YAML.
 
 The location of the file can be specified in a few different ways, in order of priority:
+
 1. The OS environment variable `AETERNITY_CONFIG` contains a filename
 2. The Erlang/OTP environment variable `-aecore config` contains a filename
 3. A file named `aeternity.{yaml,json}` exists in `${HOME}/.aeternity/aeternity/`
@@ -20,7 +21,7 @@ If all above checks fail, no user configuration is applied.
 ### Validation
 The contents of the config file will be validated against a JSON-Schema, located in the node at path `data/aeternity_config_schema.json`. If any parameters violate the schema, the node will fail to start.
 
-## Notable user configuration parameters
+## Notable parameters
 
 ### Peer-to-peer network
 
@@ -58,6 +59,7 @@ Example scheme: `node (sync > port) <-> router (sync > external_port) <-> Intern
 If you don't have port forwarding configured in your router, but your router supports UPnP or NAT-PMP, the node provides UPnP/NAT-PMP service to streamline network configuration.
 
 In order to start UPnP/NAT-PMP service:
+
 * make sure UPnP/NAT-PMP is enabled on your router;
 * in your user configuration file, set `sync` > `upnp_enabled` parameter to `true`.
 
@@ -82,6 +84,7 @@ Where the IP address should be the external IP address of the node under test (i
 
 The node provides an infrastructure for using state channes. There are two
 distinct protocols involved:
+
 * WebSocket client one
 * Noise encoded one
 
@@ -123,68 +126,6 @@ peers: []
 
 Please note that this do not prevent incoming connections, thus the node still might be connected to a network if its address is already known in that network.
 
-## Instructions
-
-The instructions below assume that:
-
-* The node is deployed in directory `~/aeternity/node`;
-* You are aiming at joining mainnet.
-
-If any of the assumptions does not hold, you need to amend the instructions accordingly.
-
-Create the config file with the below content.
-Place the config file in one of the locations specified in the [File name and location section](#file-name-and-location).
-Make sure you amend the `sync` > `port` parameter with your actual value.
-
-```yaml
----
-sync:
-    port: 3015
-
-keys:
-    dir: keys
-    peer_password: "secret"
-
-http:
-    external:
-        port: 3013
-    internal:
-        port: 3113
-
-websocket:
-    channel:
-        port: 3014
-
-mining:
-    autostart: false
-
-chain:
-    persist: true
-    db_path: ./my_db
-
-fork_management:
-    network_id: ae_mainnet
-
-```
-
-The node automatically creates the directory `db_path`, for storing the blockchain, if not present.
-
-The above sample config has `mining` > `autostart` set to `false`, so mining will not start automatically.
-To configure your node to mine, go to the [Miner configuration section](#miner-configuration).
-
-Note that YAML files have significant whitespace so make sure that you indent the file correctly and that the file ends with a newline.
-
-You can validate the configuration file before starting the node:
-```bash
-cd ~/aeternity/node
-bin/aeternity check_config aeternity.yaml
-```
-You shall read output like the following:
-```
-OK
-```
-If the file is valid YAML but does not contain a valid configuration, it prints a helpful output.
-
 ## Miner configuration
 
 The instructions below assume that you already know your `beneficiary` account public key (if you don't, see [Beneficiary account section](#beneficiary-account)).
@@ -239,6 +180,7 @@ For more details on CUDA mining go to [dedicated CUDA miner documentation](cuda-
 In order to configure who receives fees from mining on a node, you must configure a beneficiary public key.
 
 If you don't have your public key yet, you can generate a public/private key pair by using any one of the following tools:
+
 * [AirGap wallet](https://airgap.it/).
 
 If stratum is enabled, a beneficiary accounts from the stratum configuration are used instead, as stratum disables local mining.
@@ -268,3 +210,65 @@ Generated keypair with encoded pubkey: ak_2D9REvQsrAgnJgmdwPq585D8YksJC8PSAA8Msc
 
 In the example the generated public key is `ak_2D9REvQsrAgnJgmdwPq585D8YksJC8PSAA8MscQdxinbkFC7rq`, but **do not use it in your config**!
 This is just an **example** value to show what public key format you should expect after running `bin/aeternity keys_gen` command.
+
+## Example
+
+The example below assume that:
+
+* The node is deployed in directory `~/aeternity/node`;
+* You are aiming at joining mainnet.
+
+If any of the assumptions does not hold, you need to amend the instructions accordingly.
+
+Create the config file with the below content.
+Place the config file in one of the locations specified in the [File name and location section](#file-name-and-location).
+Make sure you amend the `sync` > `port` parameter with your actual value.
+
+```yaml
+---
+sync:
+    port: 3015
+
+keys:
+    dir: keys
+    peer_password: "secret"
+
+http:
+    external:
+        port: 3013
+    internal:
+        port: 3113
+
+websocket:
+    channel:
+        port: 3014
+
+mining:
+    autostart: false
+
+chain:
+    persist: true
+    db_path: ./my_db
+
+fork_management:
+    network_id: ae_mainnet
+
+```
+
+The node automatically creates the directory `db_path`, for storing the blockchain, if not present.
+
+The above sample config has `mining` > `autostart` set to `false`, so mining will not start automatically.
+To configure your node to mine, go to the [Miner configuration section](#miner-configuration).
+
+Note that YAML files have significant whitespace so make sure that you indent the file correctly and that the file ends with a newline.
+
+You can validate the configuration file before starting the node:
+```bash
+cd ~/aeternity/node
+bin/aeternity check_config aeternity.yaml
+```
+You shall read output like the following:
+```
+OK
+```
+If the file is valid YAML but does not contain a valid configuration, it prints a helpful output.
diff --git a/docs/cuda-miner.md b/docs/cuda-miner.md
@@ -1,12 +1,12 @@
-# CUDA Miner
+# Introduction
 
 The Ubuntu release packages ships with a CUDA miner.
 This documentation describes how to use the CUDA miner shipped in the Ubuntu release package, how to build it yourself (if you prefer to do so), and the related configuration of the Aeternity node.
 
 The documentation below assumes that an Aeternity node is already installed either by [release package](installation.md) or [from source](build.md), thus its dependencies are also installed.
 The documentation below assumes that the Aeternity node's source code resides in `~/aeternity/node` directory.
 
-## How to use the CUDA miner that is shipped in the release packages
+## Pre-built miner
 
 This section describes how to use the CUDA miner shipped in the Ubuntu release package.
 
@@ -16,9 +16,9 @@ In order to use the CUDA miner shipped in the Ubuntu release package, you need t
 
 Please refer to the NVIDIA documentation for how to [download][cuda-downloads] and [install][cuda-installation] the CUDA driver.
 
-### Configuration of the manually built CUDA miner
+### Configuration of the pre-built CUDA miner
 
-Once the CUDA Drive is installed, one should change the node configuration to start using the CUDA miner.
+Once the CUDA driver is installed, one should change the node configuration to start using the CUDA miner.
 The `mining.cuckoo.miner` section of `~/aeternity/node/aeternity.yaml` should be changed to:
 
 ```yaml
@@ -41,7 +41,7 @@ After configuration the node could be started (or restarted if it's already runn
 
 Available executables are: `cuda29`, `lcuda29`.
 
-## How to build a CUDA miner
+## Building
 
 This section describes how to build the CUDA miner yourself.
 

diff --git a/docs/docker.md b/docs/docker.md
@@ -1,6 +1,7 @@
-# Running an aeternity node on Docker
+# Introduction
 
 This document describes:
+
 * [How to join the mainnet using Docker](#mainnet);
 * [How to use the Docker image](#docker-image);
 * [How to join the testnet using Docker](#testnet);
@@ -34,11 +35,16 @@ You should see the console output of the running node and a lot of information r
 
 See [how to persist the blockchain data](#persisting-data) and [how to enable mining](#mining) below.
 
+## Localnet
+
+To run small local network for development and testing purposes, please refer to the [localnet repository](https://github.com/aeternity/localnet)
+
 ## Docker Image
 
 Docker image is automatically build and published on [DockerHub](https://hub.docker.com/r/aeternity/aeternity/).
 
 Please note that all the **examples** below:
+
 - use the Docker `-P` which [publish all exposed ports to the host interfaces](https://docs.docker.com/engine/reference/run/#expose-incoming-ports), for good network connectivity refer to [networking documentation](configuration.md#peer-to-peer-network) how to setup firewall and/or port mapping to the host machine
 - run the container in [foreground mode](https://docs.docker.com/engine/reference/run/#detached-vs-foreground) for easier debugging (console output).
 
@@ -110,9 +116,3 @@ The example above uses the less memory intensive lean miner, if you want to use
 You also need to provide beneficiary account in the configuration, please refer to [the beneficiary section in the configuration documentation](configuration.md#beneficiary-account) how to create one if you don't have yet.
 
 For more information see [miner configuration documentation](configuration#miner-configuration).
-
-
-## Localnet
-
-To run small local network for development and testing purposes, please refer to the [localnet repository](https://github.com/aeternity/localnet)
-
diff --git a/docs/installation.md b/docs/installation.md
@@ -1,25 +1,28 @@
-# Quick install
+# Introduction
 
-Run below command to install latest version of aeternity node.
+This document describes how to install an Aeternity node using a release binary either by:
 
-```bash
-bash <(curl -s https://raw.githubusercontent.com/aeternity/installer/v2.0.0/install.sh)
-```
+* [Quick install](#quick-install);
+* Manual install.
 
-See the documentation below detailed instructions for manual installation.
+In order to install an Aeternity node manually, you need to:
 
-# Install an Aeternity node using a release binary
+* [Retrieve the release binary](#retrieve-release-binary) corresponding to your platform;
+* [Install the required dependencies](#install-dependencies);
+* [Deploy the node](#deploy-node).
 
-This document describes how to install an Aeternity node using a release binary.
+## Quick install
 
-In order to install an Aeternity node using a release binary, you need to:
-* Retrieve the release binary corresponding to your platform;
-* Install the required dependencies;
-* Deploy the node.
+Run below command to install latest version of aeternity node and follow the instructions:
+
+```bash
+bash <(curl -s https://raw.githubusercontent.com/aeternity/installer/v2.0.0/install.sh)
+```
 
 ## Retrieve release binary
 
 The release binaries are published on [GitHub](https://github.com/aeternity/aeternity/releases) and are tested on the following platforms:
+
 * Ubuntu 16.04.3 LTS (x86-64);
 * Ubuntu 18.04 LTS (x86-64);
 * macOS High Sierra 10.13 (x86-64);
@@ -28,6 +31,7 @@ The release binaries are published on [GitHub](https://github.com/aeternity/aete
 ## Install dependencies
 
 Package dependencies are:
+
 * [Libsodium](https://download.libsodium.org/doc/) v1.0.16
 * [Openssl](https://www.openssl.org) 1.0.0
 
@@ -75,6 +79,7 @@ brew install openssl libsodium
 ```
 
 The macOS package has:
+
 * A hard dependency on OpenSSL v1.0.0 installed with [Homebrew](https://brew.sh/) in its default path `/usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib`;
 * A hard dependency on libsodium v1.0.16 installed with [Homebrew](https://brew.sh/) in its default path `/usr/local/opt/libsodium/lib/libsodium.23.dylib`.
 
@@ -88,10 +93,10 @@ ln -s "$(brew --prefix libsodium)"/lib/libsodium.23.dylib /usr/local/opt/libsodi
 ## Deploy node
 
 In the instructions below, the node is deployed in directory `~/aeternity/node`: you may prefer to deploy the node in an alternative location by amending the instructions accordingly.
+
 It is recommended that the partition where the node directory is has at least 40 GB free: this is needed for the chain and the log files.
 
 Open a Terminal window or get to the command line.
-
 Create a directory and unpack the downloaded package (you may need to amend the directory and/or file name of the package):
 ```bash
 mkdir -p ~/aeternity/node

diff --git a/docs/monitoring.md b/docs/monitoring.md
@@ -1,4 +1,4 @@
-# Network Monitoring
+# Introduction
 
 This document describes how to configure network monitoring within the node provided by `aemon` application.