Merge pull request #10 from cerc-io/mshaw_tweaks

Readme updates and quickstart options

.gitignore

@@ -0,0 +1,8 @@
+.idea
+venv
+.vscode
+laconic-so
+laconic_stack_orchestrator.egg-info
+__pycache__
+*~
+

README.md

@@ -15,31 +15,49 @@ Ensure that the following are already installed:
    $ python3 --version
    Python 3.8.10
    ```
-1. Docker (Install a current version from dockerco, don't use the version from any Linux distro)
+2. Docker (Install a current version from dockerco, don't use the version from any Linux distro)
    ```
    $ docker --version
    Docker version 20.10.17, build 100c701
    ```
+3. If installed from regular package repository (not Docker Desktop), 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
+   curl -SL https://github.com/docker/compose/releases/download/v2.11.2/docker-compose-linux-x86_64 -o $DOCKER_CONFIG/cli-plugins/docker-compose
+   chmod +x ~/.docker/cli-plugins/docker-compose
+   
+   # see https://docs.docker.com/compose/install/linux/#install-the-plugin-manually for further details
+   # or to install for all users.
+   ```
 #### Install
 1. Clone this repository:
    ```
    $ 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]...
@@ -92,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.
@@ -114,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

app/build_containers.py

@@ -41,7 +41,12 @@ def command(ctx, include, exclude):
     quiet = ctx.obj.quiet
     verbose = ctx.obj.verbose
     dry_run = ctx.obj.dry_run
+    local_stack = ctx.obj.local_stack
 
+    if local_stack:
+        dev_root_path = default=os.getcwd()[0:os.getcwd().rindex("stack-orchestrator")]
+        print(f'Local stack dev_root_path (CERC_REPO_BASE_DIR) overridden to: {dev_root_path}')
+    else:
         dev_root_path = os.path.expanduser(config("CERC_REPO_BASE_DIR", default="~/cerc"))
 
     if not quiet:

app/setup_repositories.py

@@ -68,7 +68,13 @@ def command(ctx, check_only, pull, branches_file):
         if verbose:
             print(f"Branches are: {branches}")
 
-    dev_root_path = os.path.expanduser(config("DEV_ROOT", default="~/cerc"))
+    local_stack = ctx.obj.local_stack
+
+    if local_stack:
+        dev_root_path = default=os.getcwd()[0:os.getcwd().rindex("stack-orchestrator")]
+        print(f'Local stack dev_root_path (CERC_REPO_BASE_DIR) overridden to: {dev_root_path}')
+    else:
+        dev_root_path = os.path.expanduser(config("CERC_REPO_BASE_DIR", default="~/cerc"))
 
     if not quiet:
         print(f'Dev Root is: {dev_root_path}')

cli.py

@@ -22,20 +22,23 @@ from app import deploy_system
 CONTEXT_SETTINGS = dict(help_option_names=['-h', '--help'])
 
 class Options(object):
-    def __init__(self, quiet, verbose, dry_run):
+    def __init__(self, quiet, verbose, dry_run, local_stack):
         self.quiet = quiet
         self.verbose = verbose
         self.dry_run = dry_run
+        self.local_stack = local_stack
 
 @click.group(context_settings=CONTEXT_SETTINGS)
 @click.option('--quiet', is_flag=True, default=False)
 @click.option('--verbose', is_flag=True, default=False)
 @click.option('--dry-run', is_flag=True, default=False)
+@click.option('--local_stack', is_flag=True, default=False)
+
 # See: https://click.palletsprojects.com/en/8.1.x/complex/#building-a-git-clone
 @click.pass_context
-def cli(ctx, quiet, verbose, dry_run):
+def cli(ctx, quiet, verbose, dry_run, local_stack):
     """Laconic Stack Orchestrator"""
-    ctx.obj = Options(quiet, verbose, dry_run)
+    ctx.obj = Options(quiet, verbose, dry_run, local_stack)
 
 cli.add_command(setup_repositories.command,"setup-repositories")
 cli.add_command(build_containers.command,"build-containers")

compose/docker-compose-go-ethereum-foundry.yml

@@ -18,7 +18,7 @@ services:
       DB_HOST: ipld-eth-db
       DB_PORT: 5432
       DB_PASSWORD: password
-      DB_WRITE: true
+      DB_WRITE: "true"
       DB_TYPE: postgres
       DB_DRIVER: sqlx
       DB_WAIT_FOR_SYNC: "true"

first_time_setup.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+
+python3 -m venv venv
+source ./venv/bin/activate
+pip install --editable .
+pip install shiv
+shiv -c laconic-so -o laconic-so .
+./laconic-so --verbose --local_stack setup-repositories