From fda5ceaf139e11fbccf9e2609aefcf49e3b1a3fa Mon Sep 17 00:00:00 2001
From: Michael Shaw <michael@abastionofsanity.com>
Date: Thu, 29 Sep 2022 15:56:55 -0400
Subject: [PATCH] README updates for compose plugin, running local build of
 ./laconic-so, and first_time_setup.sh

---
 README.md | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 69e7e234..96dcccfb 100644
--- a/README.md
+++ b/README.md
@@ -20,7 +20,7 @@ Ensure that the following are already installed:
    $ docker --version
    Docker version 20.10.17, build 100c701
    ```
-3. If installed from regular package repository, be aware that the compose plugin may need to be installed, as well.
+3. If installed from regular package repository, BE AWARE that the compose plugin may need to be installed, as well.
    ```
    DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
    mkdir -p $DOCKER_CONFIG/cli-plugins
@@ -35,21 +35,29 @@ Ensure that the following are already installed:
    ```
    $ git clone (https://github.com/cerc-io/stack-orchestrator.git
    ```
-1. Enter the project directory:
+2. Optional first time setup for empty dev root and fresh SO checkout:
+   ```
+   ./first_time_setup.sh
+   # e.g. /home/USER/workspace1/
+   # only contains the stack-orchestrator repo cloned in step 1.
+   # this will naively attempt to setup and activate the venv, shiv, generate a LOCAL standalone laconic-so
+   # and then setup-repositories in workspace1/
+   ```
+4. Enter the project directory:
    ```
    $ cd stack-orchestrator
    ```
-1. Create and activate a venv:
+5. Create and activate a venv:
    ```
    $ python3 -m venv venv
    $ source ./venv/bin/activate
    (venv) $
    ```
-1. Install the cli in edit mode:
+6. Install the cli in edit mode:
    ```
    $ pip install --editable .
    ```
-1. Verify installation:
+7. Verify installation:
    ```
    (venv) $ laconic-so
    Usage: laconic-so [OPTIONS] COMMAND [ARGS]...
@@ -102,17 +110,23 @@ _write-me_
 
 ## Usage
 There are three sub-commands: `setup-repositories`, `build-containers` and `deploy-system` that are generally run in order:
+
+Note: $ laconic-so will run the version installed to ~/bin, while ./laconic-so can be invoked to run locally built 
+version in a checkout
 ### Setup Repositories
 Clones the set of git repositories necessary to build a system.
 
 Note: the use of `ssh-agent` is recommended in order to avoid entering your ssh key passphrase for each repository.
 ```
-$ laconic-so --verbose setup-repositories
+$ laconic-so --verbose setup-repositories #this will default to ~/cerc or CERC_REPO_BASE_DIR from an env file
+#$ ./laconic-so --verbose --local_stack setup-repositories #this will use cwd ../ as dev_root_path
 ```
 ### Build Containers
 Builds the set of docker container images required to run a system. It takes around 10 minutes to build all the containers from cold.
 ```
-$ laconic-so --verbose build-containers
+$ laconic-so --verbose build-containers #this will default to ~/cerc or CERC_REPO_BASE_DIR from an env file
+#$ ./laconic-so --verbose --local_stack build-containers #this will use cwd ../ as dev_root_path
+
 ```
 ### Deploy System
 Uses `docker compose` to deploy a system.
@@ -124,6 +138,8 @@ $ laconic-so --verbose deploy-system --include db-sharding,contract,ipld-eth-ser
 ```
 $ laconic-so --verbose deploy-system --include db-sharding,contract,ipld-eth-server,go-ethereum-foundry down
 ```
+Note: deploy-system command interacts with most recently built container images.
+
 ## Platform Support
 Native aarm64 is _not_ currently supported. x64 emulation on ARM64 macos should work (not yet tested).
 ## Implementation