improved readme - lotus-soup (#136)

DELVING.md

@@ -23,7 +23,7 @@ This tells Testground to expose the following ports:
 * `1234` => Lotus full node RPC.
 * `2345` => Lotus storage miner RPC.
 
-### local:docker
+### `local:docker`
 
 1. Install the `lotus` binary on your host.
 2. Find the container that you want to connect to in `docker ps`.
@@ -93,7 +93,7 @@ envs miners-0
 lotus chain list
 ```
 
-### cluster:k8s
+### `cluster:k8s`
 
 Similar to `local:docker`, you pick a pod that you want to connect to and port-forward 1234 and 2345 to that specific pod, such as:
 
@@ -117,7 +117,7 @@ lotus-storage-miner storage-deals get-ask
     * `STORAGE_API_INFO=":/ip4/127.0.0.1/tcp/53624/http" FULLNODE_API_INFO=":/ip4/127.0.0.1/tcp/53623/http" lotus-storage-miner sector status <sector_no>`
     * `STORAGE_API_INFO=":/ip4/127.0.0.1/tcp/53624/http" FULLNODE_API_INFO=":/ip4/127.0.0.1/tcp/53623/http" lotus-storage-miner sector status --log <sector_no>`
 
-## Viewing logs of a particular container (local:docker)
+## Viewing logs of a particular container `local:docker`
 
 This works for both started and stopped containers. Just get the container ID
 (in double angle brackets in Testground output, on every log line), and do a:

README.md

@@ -61,12 +61,76 @@ Here are the basics of how to run the baseline deals end-to-end test case:
 testground daemon
 ```
 
-3. Run a composition for the baseline deals end-to-end test case
+3. Download required Docker images for the `lotus-soup` test plan
 
 ```
-testground run composition -f _compositions/composition.toml
+docker pull iptestground/oni-buildbase:v4
+docker pull iptestground/oni-runtime:v2
 ```
 
+Alternatively you can build them locally from the `docker-images` directory
+
+```
+cd docker-images
+./build-buildbase.sh v4
+./build-runtime.sh v2
+```
+
+4. Import the `lotus-soup` test plan into your Testground home directory
+
+```
+testground plan import --from ./lotus-soup
+```
+
+5. Init the `filecoin-ffi` Git submodule in the `extra` folder.
+
+```
+git submodule init
+```
+
+6. Compile the `filecoin-ffi` version locally (necessary if you use `local:exec`)
+
+```
+cd extra/filecoin-ffi
+make
+```
+
+7. Run a composition for the baseline deals end-to-end test case
+
+```
+testground run composition -f ./lotus-soup/_compositions/composition.toml
+```
+
+## Debugging
+
+Find commands and how-to guide on how to debug test plans at [DELVING.md](https://github.com/filecoin-project/oni/blob/master/DELVING.md)
+
+1. Querying the Lotus RPC API
+
+2. Useful commands / checks
+
+* Making sure miners are on the same chain
+
+* Checking deals
+
+* Sector queries
+
+* Sector sealing errors
+
+## `lotus-soup` Docker images history
+
+### oni-buildbase
+
+* `v1` => initial image locking in Filecoin FFI commit ca281af0b6c00314382a75ae869e5cb22c83655b.
+* `v2` => no changes; released only for aligning both images to aesthetically please @nonsense :D
+* `v3` => locking in Filecoin FFI commit 5342c7c97d1a1df4650629d14f2823d52889edd9.
+* `v4` => locking in FFI commit 6a143e06f923f3a4f544c7a652e8b4df420a3d28.
+
+### oni-runtime
+
+* `v1` => initial image with 2048 parameters.
+* `v2` => adds auxiliary tools: `net-tools netcat traceroute iputils-ping wget vim curl telnet iproute2 dnsutils`.
+
 ## Team composition
 
 * [@raulk](https://github.com/raulk) (Captain + TL)

docker-images/HISTORY.md

@@ -1,13 +0,0 @@
-# Docker image history
-
-## oni-buildbase
-
-* `v1` => initial image locking in FFI commit ca281af0b6c00314382a75ae869e5cb22c83655b.
-* `v2` => no changes; released only for aligning both images to aesthetically please @nonsense :D
-* `v3` => locking in FFI commit 5342c7c97d1a1df4650629d14f2823d52889edd9.
-* `v4` => locking in FFI commit 6a143e06f923f3a4f544c7a652e8b4df420a3d28.
-
-## oni-runtime
-
-* `v1` => initial image with 2048 parameters.
-* `v2` => adds auxiliary tools: `net-tools netcat traceroute iputils-ping wget vim curl telnet iproute2 dnsutils`.