From 480e2d40097e2e3d416c5ad27dd542bc613cd1ae Mon Sep 17 00:00:00 2001
From: Jamie Lokier <jamie@shareable.org>
Date: Mon, 26 Apr 2021 18:03:18 +0100
Subject: [PATCH] Hive: Improvements to documentation

- Explain some of the prerequisites in more detail (Go version).

- Practical issues around Go version and Docker configuration to make it work.

- Make the first example be one that works with nimbus-eth1.
  (Instead of giving an obscure error message that looks like the user's Docker
  setup is broken).

- Rename to `README.md` per convention.

Signed-off-by: Jamie Lokier <jamie@shareable.org>
---
 hive_integration/README.md | 72 ++++++++++++++++++++++++++++++++++++++
 hive_integration/readme.md | 44 -----------------------
 2 files changed, 72 insertions(+), 44 deletions(-)
 create mode 100644 hive_integration/README.md
 delete mode 100644 hive_integration/readme.md

diff --git a/hive_integration/README.md b/hive_integration/README.md
new file mode 100644
index 000000000..3d6550129
--- /dev/null
+++ b/hive_integration/README.md
@@ -0,0 +1,72 @@
+# Integration between nimbus-eth1 and Ethereum [Hive](https://github.com/ethereum/hive) test environment
+
+This is a short manual to help you quickly setup and run
+Hive.  For more detailed information please read the
+[hive documentation](https://github.com/ethereum/hive/blob/master/docs/overview.md).
+
+## Prerequisities
+
+- A Linux machine. Trust me, it does not work on Windows or MacOS.
+- Or Linux inside a VM (e.g. VirtualBox) on Windows or MacOS.
+- Docker installed and working in your Linux.
+- Go compiler installed in your Linux.
+- Go must be version 1.16 or later.
+
+## Practicalities
+
+Practically, if using an Ubuntu Linux and you want to use the version of Go
+shipped with Ubuntu, you will need Ubuntu 21.04 or later.  It's enough to run
+`apt-get install golang`.
+
+If using Ubuntu 20.04 LTS (likely because it's the long-term stable version),
+the shipped Go isn't recent enough, and there will be build errors.  You can
+either install a non-Ubuntu packaged version of Go (maybe from
+[`golang.org`](https://golang.org/), or use a more recent Ubuntu.
+
+If you want to run Hive in a Linux container, you will need Docker to work in
+the container because Hive calls Docker (a lot!).  This is sometimes called
+"Docker in Docker".  Inside LXD containers, Docker doesn't work by default, but
+usually this is remedied by setting the container flag `lxc config set
+$CONTAINER_NAME security.nesting true`, which takes effect immediately.
+
+## Building hive
+
+First you will need a working Go installation, Go 1.16 or later.  Then:
+
+```bash
+git clone https://github.com/ethereum/hive
+cd ./hive
+go build .
+```
+
+# How to run hive
+
+First copy the `nimbus-eth1/hive_intgration/nimbus` folder (from this repo)
+into the `hive/clients` folder (in the `hive` repo).
+
+Then run this command:
+
+```
+./hive --sim <simulation> --client <client(s) you want to test against>
+```
+
+Examples:
+
+```bash
+./hive --sim ethereum/consensus --client nimbus
+```
+
+or
+
+```bash
+./hive --sim devp2p/discv4 --client go-ethereum,openethereum,nimbus
+```
+
+## Available test suites / simulators
+
+- `devp2p/eth`
+- `devp2p/discv4`
+- `ethereum/sync`
+- `ethereum/consensus`
+- `ethereum/rpc`
+- `ethereum/graphql`
diff --git a/hive_integration/readme.md b/hive_integration/readme.md
deleted file mode 100644
index 5560af0ed..000000000
--- a/hive_integration/readme.md
+++ /dev/null
@@ -1,44 +0,0 @@
-nimbus-eth1 hive integration
------
-
-This is a short manual to help you quickly setup and run
-hive, for more detailed information please read
-[hive documentation](https://github.com/ethereum/hive/blob/master/docs/overview.md)
-
-## Prerequisities
-
-* A linux machine. Trust me, it does not work on Windows/MacOS
-* Or run a linux inside a VM(e.g. virtualbox) on Windows/MacOS
-* docker installed on your linux
-* go compiler installed on your linux
-
-## Building hive
-
-```bash
-git clone https://github.com/ethereum/hive
-cd ./hive
-go build .
-```
-
-## Available simulations
-
-* devp2p/eth, devp2p/discv4
-* ethereum/sync
-* ethereum/consensus
-* ethereum/rpc
-* ethereum/graphql
-
-## How to run hive
-
-First you need to copy the `hive_intgration/nimbus` into `hive/clients` folder.
-Then run this command:
-
-```
-./hive --sim <simulation> --client <client(s) you want to test against>
-```
-
-Example:
-
-```bash
-./hive --sim devp2p/discv4 --client go-ethereum,openethereum,nimbus
-```