From 9fd8e37065349d21bd5c86ba1dac5aedc04ab045 Mon Sep 17 00:00:00 2001
From: trentmc <gtrent@gmail.com>
Date: Thu, 11 May 2023 11:30:32 +0900
Subject: [PATCH] Fix #364: Barge has gotchas. To help, update README

---
 README.md | 44 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 38 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 6ea6726..2dc4bf1 100644
--- a/README.md
+++ b/README.md
@@ -8,8 +8,11 @@
 
 - [Prerequisites](#prerequisites)
 - [Get Started](#get-started)
-- [Options](#options)
+- [Cleanup](#cleanup)
+  - [Troubleshooting](#troubleshootin)
+- [Startup Options](#startup-options)
   - [Component Versions](#component-versions-and-exposed-ports)
+  - [Log levels](#log-levels)
   - [All Options](#all-options)
 - [Docker Building Blocks](#docker-building-blocks)
   - [Aquarius](#aquarius)
@@ -56,9 +59,41 @@ To clean up your environment, you can run
 > ./cleanup.sh
 > ```
 
-This will stop & remove any ocean related containers, then delete any volumes and networks created by barge
+This will stop & remove any ocean related containers, then delete any volumes and networks created by barge.
 
-## Options
+
+### Troubleshooting
+
+If your code using Barge hits `KeyError: "development"`, this is a Barge issue: Barge couldn't deploy the contracts and update `address.json` in `~/.ocean/`. _Further_ cleanup is needed. Further cleanup can fix other issues too. Here are tactics.
+
+Tactic: clean up old Docker containers
+```console
+docker system prune -a --volumes
+```
+
+Tactic: delete Ocean cache, or a sub-directory of it. (This is not part of cleanup.sh in case you want to preserve parts of `~/.ocean/`.)
+```console
+# delete whole cache
+rm -rf ~/.ocean
+
+# OR, delete sub-directory
+# (find the sub-directory, and rm -rf it)
+```
+
+Tactic: Kill redis or postgres processes. Why: they usually have autostart enabled and can interfere with Barge.
+```console
+# use ps. Do as superuser to ensure you see the process.
+sudo ps aux | grep redis
+sudo ps aux | grep postgresql
+
+# If you see unwanted processes, kill them by process id. -9 to force
+kill -9 <pid>
+```
+
+Tactic: reboot your computer. Why: will stop any other unwanted process.
+
+
+## Startup Options
 
 The startup script comes with a set of options for customizing various things.
 
@@ -83,8 +118,6 @@ The default versions are always a combination of component versions which are co
 | C2d                 |                    | multiple components               | 172.15.0.12,172.15.0.13     | 31000 -> 31000  |
 
 
-
-
 You can override the Docker image tag used for a particular component by setting its associated environment variable before calling `start_ocean.sh`:
 
 - `AQUARIUS_VERSION`
@@ -138,7 +171,6 @@ export AQUARIUS_LOG_LEVEL=DEBUG
 | `--with-c2d`               | Runs a local C2D Cluster                                                                        |
 
 
-
 ## Docker Building Blocks
 
 Barge consists of a set of building blocks that can be combined to form a local test environment. By default all building blocks will be started by the `start_ocean.sh` script.