diff --git a/README.md b/README.md index db879530..b2c86f4b 100644 --- a/README.md +++ b/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) -- [Docker](https://docs.docker.com/get-docker/) -- [Docker Compose](https://docs.docker.com/compose/install/) +- [Python3](https://wiki.python.org/moin/BeginnersGuide/Download): `python3 --version` >= `3.10.8` +- [Docker](https://docs.docker.com/get-docker/): `docker --version` >= `20.10.21` +- [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 diff --git a/.github/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 83% rename from .github/CONTRIBUTING.md rename to docs/CONTRIBUTING.md index 5b73c490..93437364 100644 --- a/.github/CONTRIBUTING.md +++ b/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). diff --git a/docs/images/laconic-stack.png b/docs/images/laconic-stack.png new file mode 100644 index 00000000..6d0ab4c0 Binary files /dev/null and b/docs/images/laconic-stack.png differ diff --git a/docs/images/laconic-stack.png.REMOVED.git-id b/docs/images/laconic-stack.png.REMOVED.git-id deleted file mode 100644 index e7ffd2c5..00000000 --- a/docs/images/laconic-stack.png.REMOVED.git-id +++ /dev/null @@ -1 +0,0 @@ -8f6452ed13e85a447103a7fff7cf3fb8ff5ea51a \ No newline at end of file diff --git a/docs/spec.md b/docs/spec.md index a3f4af4d..7bf038cb 100644 --- a/docs/spec.md +++ b/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). -Files required to build each container image are stored under `./container-build/` -Files required at deploy-time are stored under `./config/` + +The orchestrator's operation is driven by files shown below. + +- `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-db.yml +│   ├── docker-compose-eth-probe.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-prometheus-grafana.yml +│   ├── docker-compose-keycloak.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 -├── container-image-list.txt -├── repository-list.txt +│   ├── cerc-test-container +│   ├── cerc-test-contract +│   ├── 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 ```