Merge pull request #144 from cerc-io/docs-updates

Docs updates

Former-commit-id: 3cef5eb262803d5e485b15146f3ddd79e4d1de4e

README.md

@@ -8,9 +8,9 @@ Stack Orchestrator allows building and deployment of a Laconic Stack on a single
 
 Ensure that the following are already installed:
 
-- [Python3](https://wiki.python.org/moin/BeginnersGuide/Download)
+- [Python3](https://wiki.python.org/moin/BeginnersGuide/Download): `python3 --version` >= `3.10.8`
-- [Docker](https://docs.docker.com/get-docker/) 
+- [Docker](https://docs.docker.com/get-docker/): `docker --version` >= `20.10.21`
-- [Docker Compose](https://docs.docker.com/compose/install/)
+- [Docker Compose](https://docs.docker.com/compose/install/): `docker-compose --version` >= `2.13.0`
 
 Note: if installing docker-compose via package manager (as opposed to Docker Desktop), you must [install the plugin](https://docs.docker.com/compose/install/linux/#install-the-plugin-manually), e.g., on Linux:
 
@@ -97,7 +97,7 @@ laconic-so --verbose deploy-system --include ipld-eth-db,go-ethereum-foundry,ipl
 
 ## Contributing
 
-See the [CONTRIBUTING.md](.github/CONTRIBUTING.md) for developer mode install.
+See the [CONTRIBUTING.md](/docs/CONTRIBUTING.md) for developer mode install.
 
 ## Platform Support
 

docs/CONTRIBUTING.md

@@ -5,8 +5,11 @@ Thank you for taking the time to make a contribution to Stack Orchestrator.
 ## Install (developer mode)
 
 Suitable for developers either modifying or debugging the orchestrator Python code:
-#### Prerequisites
+
-In addition to the binary install prerequisites listed above, the following are required:
+### Prerequisites
+
+In addition to the pre-requisites listed in the [README](/README.md), the following are required:
+
 1. Python venv package
    This may or may not be already installed depending on the host OS and version. Check by running:
    ```
@@ -18,26 +21,32 @@ In addition to the binary install prerequisites listed above, the following are
    ```
    $ apt install python3.10-venv
    ```
-#### Install
+
+### Install
+
 1. Clone this repository:
    ```
    $ git clone (https://github.com/cerc-io/stack-orchestrator.git
    ```
-4. Enter the project directory:
+
+2. Enter the project directory:
    ```
    $ cd stack-orchestrator
    ```
-5. Create and activate a venv:
+
+3. Create and activate a venv:
    ```
    $ python3 -m venv venv
    $ source ./venv/bin/activate
    (venv) $
    ```
-6. Install the cli in edit mode:
+
+4. Install the cli in edit mode:
    ```
    $ pip install --editable .
    ```
-7. Verify installation:
+
+5. Verify installation:
    ```
    (venv) $ laconic-so
    Usage: laconic-so [OPTIONS] COMMAND [ARGS]...
@@ -56,19 +65,23 @@ In addition to the binary install prerequisites listed above, the following are
     setup-repositories  git clone the set of repositories required to build...
    ```
 
-#### Build a zipapp (single file distributable script)
+## Build a zipapp (single file distributable script)
+
 Use shiv to build a single file Python executable zip archive of laconic-so:
+
 1. Install [shiv](https://github.com/linkedin/shiv):
    ```
    $ (venv) pip install shiv
    $ (venv) pip install wheel
    ```
-1. Run shiv to create a zipapp file:
+
+2. Run shiv to create a zipapp file:
    ```
    $ (venv)  shiv -c laconic-so -o laconic-so .
    ```
    This creates a file `./laconic-so` that is executable outside of any venv, and on other machines and OSes and architectures, and requiring only the system Python3:
-1. Verify it works:
+
+3. Verify it works:
    ```
    $ cp stack-orchetrator/laconic-so ~/bin
    $ laconic-so
@@ -88,4 +101,4 @@ Use shiv to build a single file Python executable zip archive of laconic-so:
       setup-repositories  git clone the set of repositories required to build...
    ```
 
-
+For cutting releases, use the [shiv build script](/scripts/build_shiv_package.sh).

docs/images/laconic-stack.png.REMOVED.git-id

@@ -1 +0,0 @@
-8f6452ed13e85a447103a7fff7cf3fb8ff5ea51a

docs/spec.md

@@ -1,37 +1,82 @@
-# Spec
+# Specification
 
-TODO: update
 
 ## Implementation
-The orchestrator's operation is driven by files shown below. `repository-list.txt` container the list of git repositories; `container-image-list.txt` contains
+
-the list of container image names, while `clister-list.txt` specifies the set of compose components (corresponding to individual docker-compose-xxx.yml files which may in turn specify more than one container).
+The orchestrator's operation is driven by files shown below. 
-Files required to build each container image are stored under `./container-build/<container-name>`
+
-Files required at deploy-time are stored under `./config/<component-name>`
+- `repository-list.txt` contains the list of git repositories; 
+- `container-image-list.txt` contains the list of container image names
+- `pod-list.txt` specifies the set of compose components (corresponding to individual docker-compose-xxx.yml files which may in turn specify more than one container).
+- `container-build/` contains the files required to build each container image
+- `config/` contains the files required at deploy time
+
 ```
+├── container-image-list.txt
 ├── pod-list.txt
+├── repository-list.txt
 ├── compose
 │   ├── docker-compose-contract.yml
-│   ├── docker-compose-db-sharding.yml
+│   ├── docker-compose-eth-probe.yml
-│   ├── docker-compose-db.yml
 │   ├── docker-compose-eth-statediff-fill-service.yml
+│   ├── docker-compose-fixturenet-eth.yml
+│   ├── docker-compose-fixturenet-laconicd.yml
 │   ├── docker-compose-go-ethereum-foundry.yml
 │   ├── docker-compose-ipld-eth-beacon-db.yml
 │   ├── docker-compose-ipld-eth-beacon-indexer.yml
+│   ├── docker-compose-ipld-eth-db.yml
 │   ├── docker-compose-ipld-eth-server.yml
-│   ├── docker-compose-lighthouse.yml
+│   ├── docker-compose-keycloak.yml
-│   └── docker-compose-prometheus-grafana.yml
+│   ├── docker-compose-laconicd.yml
+│   ├── docker-compose-prometheus-grafana.yml
+│   ├── docker-compose-test.yml
+│   ├── docker-compose-tx-spammer.yml
+│   ├── docker-compose-watcher-erc20.yml
+│   ├── docker-compose-watcher-erc721.yml
+│   ├── docker-compose-watcher-mobymask.yml
+│   └── docker-compose-watcher-uniswap-v3.yml
 ├── config
-│   └── ipld-eth-server
+│   ├── fixturenet-eth
+│   ├── fixturenet-laconicd
+│   ├── ipld-eth-beacon-indexer
+│   ├── ipld-eth-server
+│   ├── keycloak
+│   ├── postgresql
+│   ├── tx-spammer
+│   ├── watcher-erc20
+│   ├── watcher-erc721
+│   ├── watcher-mobymask
+│   └── watcher-uniswap-v3
 ├── container-build
+│   ├── cerc-builder-js
+│   ├── cerc-eth-probe
 │   ├── cerc-eth-statediff-fill-service
+│   ├── cerc-eth-statediff-service
+│   ├── cerc-fixturenet-eth-geth
+│   ├── cerc-fixturenet-eth-lighthouse
 │   ├── cerc-go-ethereum
 │   ├── cerc-go-ethereum-foundry
 │   ├── cerc-ipld-eth-beacon-db
 │   ├── cerc-ipld-eth-beacon-indexer
 │   ├── cerc-ipld-eth-db
 │   ├── cerc-ipld-eth-server
+│   ├── cerc-keycloak
+│   ├── cerc-laconic-registry-cli
+│   ├── cerc-laconicd
 │   ├── cerc-lighthouse
-│   └── cerc-test-contract
+│   ├── cerc-test-container
-├── container-image-list.txt
+│   ├── cerc-test-contract
-├── repository-list.txt
+│   ├── cerc-tx-spammer
+│   ├── cerc-uniswap-v3-info
+│   ├── cerc-watcher-erc20
+│   ├── cerc-watcher-erc721
+│   ├── cerc-watcher-mobymask
+│   ├── cerc-watcher-uniswap-v3
+└── stacks
+    ├── erc20
+    ├── erc721
+    ├── fixturenet-eth
+    ├── fixturenet-laconicd
+    ├── mobymask
+    └── uniswap-v3
 ```