Merge pull request #166 from cerc-io/dboreham/fix-fixturenet-status

Fix status script

Former-commit-id: fc31b44b5a

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
 

app/data/compose/docker-compose-fixturenet-eth-metrics.yml

@@ -0,0 +1,21 @@
+version: "3.2"
+services:
+  prometheus:
+    restart: always
+    image: prom/prometheus
+    depends_on:
+      fixturenet-eth-geth-1:
+        condition: service_healthy
+    volumes:
+      - ../config/fixturenet-eth-metrics/prometheus/etc:/etc/prometheus
+    ports:
+      - "9090"
+  grafana:
+    restart: always
+    image: grafana/grafana
+    volumes:
+      - ../config/fixturenet-eth-metrics/grafana/etc/provisioning/dashboards:/etc/grafana/provisioning/dashboards
+      - ../config/fixturenet-eth-metrics/grafana/etc/provisioning/datasources:/etc/grafana/provisioning/datasources
+      - ../config/fixturenet-eth-metrics/grafana/etc/dashboards:/etc/grafana/dashboards
+    ports:
+      - "3000"

app/data/compose/docker-compose-fixturenet-eth.yml

@@ -20,6 +20,7 @@ services:
       CERC_REMOTE_DEBUG: "true"
       CERC_RUN_STATEDIFF: "detect"
       CERC_STATEDIFF_DB_NODE_ID: 1
+      CERC_SCRIPT_DEBUG: ${CERC_SCRIPT_DEBUG}
     env_file:
       - ../config/fixturenet-eth/fixturenet-eth.env
     image: cerc/fixturenet-eth-geth:local

app/data/compose/docker-compose-ipld-eth-server.yml

@@ -20,16 +20,24 @@ services:
       DATABASE_USER: "vdbm"
       DATABASE_PASSWORD: "password"
       ETH_CHAIN_ID: 99
-      ETH_FORWARD_ETH_CALLS: $eth_forward_eth_calls
-      ETH_PROXY_ON_ERROR: $eth_proxy_on_error
-      ETH_HTTP_PATH: $eth_http_path
+      ETH_FORWARD_ETH_CALLS: "false"
+      ETH_FORWARD_GET_STORAGE_AT: "false"
+      ETH_PROXY_ON_ERROR: "false"
+      METRICS: "true"
+      PROM_HTTP: "true"
+      PROM_HTTP_ADDR: "0.0.0.0"
+      PROM_HTTP_PORT: "8090"
+      LOGRUS_LEVEL: "debug"
+      CERC_REMOTE_DEBUG: "true"
     volumes:
       - type: bind
         source: ../config/ipld-eth-server/chain.json
         target: /tmp/chain.json
     ports:
-      - "127.0.0.1:8081:8081"
-      - "127.0.0.1:8082:8082"
+      - "8081"
+      - "8082"
+      - "8090"
+      - "40000"
     healthcheck:
       test: ["CMD", "nc", "-v", "localhost", "8081"]
       interval: 20s

app/data/compose/docker-compose-keycloak.yml

@@ -29,9 +29,17 @@ services:
         condition: service_healthy
   keycloak-nginx:
     image: nginx:1.23-alpine
+    restart: always
     volumes:
       - ../config/keycloak/nginx:/etc/nginx/conf.d
     ports:
       - 80
     depends_on:
       - keycloak
+  keycloak-nginx-prometheus-exporter:
+    image: nginx/nginx-prometheus-exporter
+    restart: always
+    environment:
+      - SCRAPE_URI=http://keycloak-nginx:80/stub_status
+    depends_on:
+      - keycloak-nginx

app/data/compose/docker-compose-prometheus-grafana.yml

@@ -1,21 +0,0 @@
-version: "3.2"
-services:
-  # If you want prometheus to work, you must update the following file in the ops repo locally.
-  # localhost:6060 --> go-ethereum:6060
-  prometheus:
-    restart: always
-    user: "987"
-    image: prom/prometheus
-    volumes:
-      - ${cerc_ops}/metrics/etc:/etc/prometheus
-      - ./prometheus-data:/prometheus
-    ports:
-      - "127.0.0.1:9090:9090"
-  grafana:
-    restart: always
-    user: "472"
-    image: grafana/grafana
-    volumes:
-      - ./grafana-data:/var/lib/grafana
-    ports:
-      - "127.0.0.1:3000:3000"

app/data/compose/docker-compose-test.yml

@@ -3,3 +3,5 @@ services:
   test:
     image: cerc/test-container:local
     restart: always
+    ports:
+      - "80"

app/data/config/fixturenet-eth-metrics/grafana/etc/provisioning/dashboards/dashboards.yml

@@ -0,0 +1,9 @@
+apiVersion: 1
+
+providers:
+  - name: dashboards
+    type: file
+    updateIntervalSeconds: 10
+    options:
+      path: /etc/grafana/dashboards
+      foldersFromFilesStructure: true

app/data/config/fixturenet-eth-metrics/grafana/etc/provisioning/datasources/prometheus.yml

@@ -0,0 +1,19 @@
+apiVersion: 1
+
+datasources:
+  - id: 1
+    uid: jZUuGao4k
+    orgId: 1
+    name: Prometheus
+    type: prometheus
+    typeName: Prometheus
+    typeLogoUrl: public/app/plugins/datasource/prometheus/img/prometheus_logo.svg
+    access: proxy
+    url: http://prometheus:9090
+    user: ""
+    database: ""
+    basicAuth: false
+    isDefault: true
+    jsonData:
+      httpMethod: POST
+    readOnly: false

app/data/config/fixturenet-eth-metrics/prometheus/etc/prometheus.yml

@@ -0,0 +1,34 @@
+global:
+  scrape_interval: 5s
+  evaluation_interval: 15s
+
+scrape_configs:
+  # ipld-eth-server
+  - job_name: 'ipld-eth-server'
+    metrics_path: /metrics
+    scrape_interval: 5s
+    static_configs:
+    - targets: ['ipld-eth-server:8090']
+
+  # geth
+  - job_name: 'geth'
+    metrics_path: /debug/metrics/prometheus
+    scheme: http
+    static_configs:
+    - targets: ['fixturenet-eth-geth-1:6060']
+
+  # nginx
+  - job_name: 'nginx'
+    scrape_interval: 5s
+    metrics_path: /metrics
+    scheme: http
+    static_configs:
+      - targets: ['keycloak-nginx-prometheus-exporter:9113']
+
+  # keycloak
+  - job_name: 'keycloak'
+    scrape_interval: 5s
+    metrics_path: /auth/realms/cerc/metrics
+    scheme: http
+    static_configs:
+      - targets: ['keycloak:8080']

app/data/config/fixturenet-eth/fixturenet-eth.env

@@ -19,3 +19,5 @@ CERC_STATEDIFF_DB_USER="vdbm"
 CERC_STATEDIFF_DB_PASSWORD="password"
 CERC_STATEDIFF_DB_GOOSE_MIN_VER=23
 CERC_STATEDIFF_DB_LOG_STATEMENTS="false"
+
+CERC_GETH_VMODULE="statediff/*=5,rpc/*=5"

app/data/config/keycloak/nginx/keycloak_proxy.conf

@@ -20,16 +20,19 @@ server {
         proxy_pass  http://fixturenet-eth-geth-1:8545;
     }
 
-### ipld-eth-server
+## ipld-eth-server
 #    location ~ ^/ipld/eth/([^/]*)$ {
 #        set $apiKey $1;
 #        if ($apiKey = '') {
 #          set $apiKey $http_X_API_KEY;
 #        }
 #        auth_request /auth;
+#        auth_request_set $user_id $sent_http_x_user_id;
 #        proxy_buffering off;
 #        rewrite /.*$ / break;
 #        proxy_pass  http://ipld-eth-server:8081;
+#        proxy_set_header X-Original-Remote-Addr $remote_addr;
+#        proxy_set_header X-User-Id $user_id;
 #    }
 #
 #    location ~ ^/ipld/gql/([^/]*)$ {
@@ -42,14 +45,14 @@ server {
 #        rewrite /.*$ / break;
 #        proxy_pass  http://ipld-eth-server:8082;
 #    }
-#
-### lighthouse
-#    location /beacon/ {
-#        set $apiKey $http_X_API_KEY;
-#        auth_request /auth;
-#        proxy_buffering off;
-#        proxy_pass  http://fixturenet-eth-lighthouse-1:8001/;
-#    }
+
+## lighthouse
+    location /beacon/ {
+        set $apiKey $http_X_API_KEY;
+        auth_request /auth;
+        proxy_buffering off;
+        proxy_pass  http://fixturenet-eth-lighthouse-1:8001/;
+    }
 
     location = /auth {
         internal;
@@ -63,7 +66,7 @@ server {
         proxy_set_header X-Original-Host $host;
     }
 
-#    location = /basic_status {
-#        stub_status;
-#    }
+    location = /stub_status {
+        stub_status;
+    }
 }

app/data/container-build/cerc-builder-gerbil/Dockerfile

@@ -0,0 +1,25 @@
+# From: https://github.com/vyzo/gerbil/blob/master/docker/Dockerfile
+FROM gerbil/ubuntu
+
+# Install the Solidity compiler (latest stable version)
+# and guile
+# and libsecp256k1-dev
+RUN apt-get update && export DEBIAN_FRONTEND=noninteractive && export DEBCONF_NOWARNINGS="yes" && \
+    apt-get install -y software-properties-common && \
+    add-apt-repository ppa:ethereum/ethereum && \
+    apt-get update && \
+    apt-get install -y solc && \
+    apt-get install -y guile-3.0 && \
+    apt-get install -y libsecp256k1-dev && \
+    apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+
+RUN mkdir /scripts
+COPY install-dependencies.sh /scripts
+
+RUN bash /scripts/install-dependencies.sh
+
+# Needed to prevent git from raging about /src
+RUN git config --global --add safe.directory /src
+
+COPY entrypoint.sh /scripts
+ENTRYPOINT ["/scripts/entrypoint.sh"]

app/data/container-build/cerc-builder-gerbil/README.md

@@ -0,0 +1,21 @@
+## Gerbil Scheme Builder
+
+This container is designed to be used as a simple "build runner" environment for building and running Scheme projects using Gerbil and gerbil-ethereum. Its primary purpose is to allow build/test/run of gerbil code without the need to install and configure all the necessary prerequisites and dependencies on the host system.
+
+### Usage
+
+First build the container with:
+
+```
+$ laconic-so build-containers --include cerc/builder-gerbil
+```
+
+Now, assuming a gerbil project located at `~/projects/my-project`, run bash in the container mounting the project with:
+
+```
+$ docker run -it -v $HOME/projects/my-project:/src cerc/builder-gerbil:latest bash
+root@7c4124bb09e3:/src#
+```
+
+Now gerbil commands can be run.
+

app/data/container-build/cerc-builder-gerbil/entrypoint.sh

@@ -0,0 +1,2 @@
+#!/bin/sh
+exec "$@"

app/data/container-build/cerc-builder-gerbil/install-dependencies.sh

@@ -0,0 +1,15 @@
+DEPS=(github.com/fare/gerbil-utils
+      github.com/fare/gerbil-poo
+      github.com/fare/gerbil-crypto
+      github.com/fare/gerbil-persist
+      github.com/fare/gerbil-ethereum
+      github.com/drewc/gerbil-swank
+      github.com/drewc/drewc-r7rs-swank
+      github.com/drewc/smug-gerbil
+      github.com/drewc/ftw
+      github.com/vyzo/gerbil-libp2p
+      ) ;
+for i in ${DEPS[@]} ; do
+  gxpkg install $i &&
+  gxpkg build $i
+done

app/data/container-build/cerc-fixturenet-eth-geth/run-el.sh

@@ -1,5 +1,9 @@
 #!/bin/bash
 
+if [ -n "$CERC_SCRIPT_DEBUG" ]; then
+    set -x
+fi
+
 ETHERBASE=`cat /opt/testnet/build/el/accounts.csv | head -1 | cut -d',' -f2`
 NETWORK_ID=`cat /opt/testnet/el/el-config.yaml | grep 'chain_id' | awk '{ print $2 }'`
 NETRESTRICT=`ip addr | grep inet | grep -v '127.0' | awk '{print $2}'`
@@ -28,7 +32,9 @@ else
     echo -n "$JWT" > /opt/testnet/build/el/jwtsecret
 
     if [ "$CERC_RUN_STATEDIFF" == "detect" ] && [ -n "$CERC_STATEDIFF_DB_HOST" ]; then
-      if [ -n "$(dig $CERC_STATEDIFF_DB_HOST +short)" ]; then
+      dig_result=$(dig $CERC_STATEDIFF_DB_HOST +short)
+      dig_status_code=$?
+      if [[ $dig_status_code = 0 && -n $dig_result ]]; then
         echo "Statediff DB at $CERC_STATEDIFF_DB_HOST"
         CERC_RUN_STATEDIFF="true"
       else

app/data/container-build/cerc-fixturenet-eth-lighthouse/Dockerfile

@@ -27,4 +27,8 @@ RUN cd /opt/testnet && make genesis-cl
 # Work around some bugs in lcli where the default path is always used.
 RUN mkdir -p /root/.lighthouse && cd /root/.lighthouse && ln -s /opt/testnet/build/cl/testnet
 
+RUN mkdir -p /scripts
+COPY scripts/status-internal.sh /scripts
+COPY scripts/status.sh /scripts
+
 ENTRYPOINT ["/opt/testnet/run.sh"]

app/data/container-build/cerc-fixturenet-eth-lighthouse/scripts/status-internal.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Wrapper to facilitate using status.sh inside the container
+if [ -n "$CERC_SCRIPT_DEBUG" ]; then
+    set -x
+fi
+export LIGHTHOUSE_BASE_URL="http://fixturenet-eth-lighthouse-1:8001"
+export GETH_BASE_URL="http://fixturenet-eth-geth-1:8545"
+# See: https://stackoverflow.com/a/246128/1701505
+SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
+$SCRIPT_DIR/status.sh

app/data/container-build/cerc-fixturenet-eth-lighthouse/scripts/status.sh

@@ -1,5 +1,7 @@
-#!/bin/bash
-
+#!/usr/bin/env bash
+if [ -n "$CERC_SCRIPT_DEBUG" ]; then
+    set -x
+fi
 STATUSES=("geth to generate DAG" "beacon phase0" "beacon altair" "beacon bellatrix pre-merge" "beacon bellatrix merge")
 STATUS=0
 
@@ -7,13 +9,17 @@ STATUS=0
 LIGHTHOUSE_BASE_URL=${LIGHTHOUSE_BASE_URL}
 GETH_BASE_URL=${GETH_BASE_URL}
 
+# TODO: Docker commands below should be replaced by some interface into stack orchestrator
+# or some execution environment-neutral mechanism.
 if [ -z "$LIGHTHOUSE_BASE_URL" ]; then
-  LIGHTHOUSE_PORT=`docker ps -f "name=fixturenet-eth-lighthouse-1-1" --format "{{.Ports}}" | head -1 | cut -d':' -f2 | cut -d'-' -f1`
+  LIGHTHOUSE_CONTAINER=`docker ps -q -f "name=fixturenet-eth-lighthouse-1-1"`
+  LIGHTHOUSE_PORT=`docker port $LIGHTHOUSE_CONTAINER 8001 | cut -d':' -f2`
   LIGHTHOUSE_BASE_URL="http://localhost:${LIGHTHOUSE_PORT}"
 fi
 
 if [ -z "$GETH_BASE_URL" ]; then
-  GETH_PORT=`docker ps -f "name=fixturenet-eth-geth-1-1" --format "{{.Ports}}" | head -1 | cut -d':' -f2 | cut -d'-' -f1`
+  GETH_CONTAINER=`docker ps -q -f "name=fixturenet-eth-geth-1-1"`
+  GETH_PORT=`docker port $GETH_CONTAINER 8545 | cut -d':' -f2`
   GETH_BASE_URL="http://localhost:${GETH_PORT}"
 fi
 

app/data/container-build/cerc-go-ethereum-foundry/Dockerfile

@@ -1,4 +1,6 @@
-FROM ghcr.io/foundry-rs/foundry
+# Use locally build foundry base image to work around there being
+# no aarm64 image published.
+FROM foundry-rs/foundry:local
 
 RUN apk update ; apk add --no-cache --allow-untrusted ca-certificates curl bash git jq
 RUN apk add --no-cache --upgrade grep

app/data/container-build/cerc-keycloak/Dockerfile

@@ -1,4 +1,4 @@
 FROM quay.io/keycloak/keycloak:20.0
 WORKDIR /opt/keycloak/providers
 RUN curl -L https://github.com/aerogear/keycloak-metrics-spi/releases/download/2.5.3/keycloak-metrics-spi-2.5.3.jar --output keycloak-metrics-spi.jar
-RUN curl -L https://github.com/cerc-io/keycloak-api-key-demo/releases/download/v0.1/api-key-module-0.1.jar --output api-key-module.jar
+RUN curl -L https://github.com/cerc-io/keycloak-api-key-demo/releases/download/v0.2/api-key-module-0.2.jar --output api-key-module.jar

app/data/container-build/cerc-test-container/Dockerfile

@@ -1,4 +1,11 @@
-FROM alpine:latest
+FROM ubuntu:latest
+
+RUN apt-get update && export DEBIAN_FRONTEND=noninteractive && export DEBCONF_NOWARNINGS="yes" && \
+    apt-get install -y software-properties-common && \
+    apt-get install -y nginx && \
+    apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
+
+EXPOSE 80
 
 COPY run.sh /app/run.sh
 

app/data/container-build/cerc-test-container/run.sh

@@ -12,5 +12,5 @@ else
     echo `date` > $EXISTSFILENAME
 fi
 
-# Sleep forever to keep docker happy
-while true; do sleep 10; done
+# Run nginx which will block here forever
+/usr/sbin/nginx -g "daemon off;"

app/data/container-build/foundry-rs-foundry/build.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Build foundry-rs/foundry
+# HACK below : TARGETARCH needs to be derived from the host environment
+docker build -t foundry-rs/foundry:local ${CERC_REPO_BASE_DIR}/foundry

app/data/container-image-list.txt

@@ -1,3 +1,4 @@
+foundry-rs/foundry
 cerc/test-contract
 cerc/eth-statediff-fill-service
 cerc/eth-statediff-service
@@ -22,3 +23,4 @@ cerc/eth-probe
 cerc/builder-js
 cerc/keycloak
 cerc/tx-spammer
+cerc/builder-gerbil

app/data/pod-list.txt

@@ -6,10 +6,10 @@ ipld-eth-beacon-db
 ipld-eth-beacon-indexer
 ipld-eth-server
 lighthouse
-prometheus-grafana
 laconicd
 fixturenet-laconicd
 fixturenet-eth
+fixturenet-eth-metrics
 watcher-mobymask
 watcher-erc20
 watcher-erc721

app/data/repository-list.txt

@@ -16,3 +16,4 @@ vulcanize/uniswap-v3-info
 vulcanize/assemblyscript
 cerc-io/eth-probe
 cerc-io/tx-spammer
+foundry-rs/foundry

app/data/stacks/erc20/stack.yml

@@ -13,6 +13,6 @@ containers:
   - cerc/watcher-erc20
 pods:
   - go-ethereum-foundry
-  - db
+  - ipld-eth-db
   - ipld-eth-server
   - watcher-erc20

app/data/stacks/erc721/stack.yml

@@ -13,6 +13,6 @@ containers:
   - cerc/watcher-erc721
 pods:
   - go-ethereum-foundry
-  - db
+  - ipld-eth-db
   - ipld-eth-server
   - watcher-erc721

app/data/stacks/fixturenet-eth/README.md

@@ -4,12 +4,12 @@ Instructions for deploying a local a geth + lighthouse blockchain "fixturenet" f
 
 ## Clone required repositories
 ```
-$ laconic-so setup-repositories --include cerc-io/go-ethereum
+$ laconic-so --stack fixturenet-eth setup-repositories
 ```
 
 ## Build the fixturenet-eth containers
 ```
-$ laconic-so build-containers --include cerc/go-ethereum,cerc/lighthouse,cerc/fixturenet-eth-geth,cerc/fixturenet-eth-lighthouse
+$ laconic-so --stack fixturenet-eth build-containers
 ```
 This should create several container images in the local image registry: 
 
@@ -20,7 +20,7 @@ This should create several container images in the local image registry:
 
 ## Deploy the stack
 ```
-$ laconic-so deploy-system --include fixturenet-eth up
+$ laconic-so --stack fixturenet-eth deploy-system up
 ```
 
 ## Check status

app/data/stacks/fixturenet-eth/stack.yml

@@ -1,12 +1,13 @@
 version: "1.0"
 name: fixturenet-eth
+decription: "Ethereum Fixturenet"
 repos:
   - cerc-io/go-ethereum
-  - cerc-io/lighthouse
+  - cerc-io/tx-spammer
 containers:
   - cerc/go-ethereum
   - cerc/lighthouse
   - cerc/fixturenet-eth-geth
   - cerc/fixturenet-eth-lighthouse
 pods:
-  - fixturenet-eth
+  - fixturenet-eth

app/data/stacks/test/README.md

@@ -0,0 +1,3 @@
+# Test Stack
+
+A stack for test/demo purposes.

app/data/stacks/test/stack.yml

@@ -0,0 +1,9 @@
+version: "1.0"
+name: test
+description: "A test stack"
+repos:
+  - cerc-io/laconicd
+containers:
+  - cerc/test-container
+pods:
+  - test

app/data/version.txt

@@ -1,2 +1,2 @@
 # This file should be re-generated running: scripts/update-version-file.sh script
-v1.0.11-alpha-edbf674
+v1.0.16-ecf943b

app/deploy_system.py

@@ -30,13 +30,14 @@ from .util import include_exclude_check, get_parsed_stack_config
 @click.option("--exclude", help="don\'t start these components")
 @click.option("--cluster", help="specify a non-default cluster name")
 @click.argument('command', required=True)  # help: command: up|down|ps
-@click.argument('services', nargs=-1)  # help: command: up|down|ps <service1> <service2>
+@click.argument('extra_args', nargs=-1)  # help: command: up|down|ps <service1> <service2>
 @click.pass_context
-def command(ctx, include, exclude, cluster, command, services):
+def command(ctx, include, exclude, cluster, command, extra_args):
     '''deploy a stack'''
 
     # TODO: implement option exclusion and command value constraint lost with the move from argparse to click
 
+    debug = ctx.obj.debug
     quiet = ctx.obj.quiet
     verbose = ctx.obj.verbose
     dry_run = ctx.obj.dry_run
@@ -87,17 +88,41 @@ def command(ctx, include, exclude, cluster, command, services):
     # See: https://gabrieldemarmiesse.github.io/python-on-whales/sub-commands/compose/
     docker = DockerClient(compose_files=compose_files, compose_project_name=cluster)
 
-    services_list = list(services) or None
+    extra_args_list = list(extra_args) or None
 
     if not dry_run:
         if command == "up":
+            if debug:
+                os.environ["CERC_SCRIPT_DEBUG"] = "true"
             if verbose:
-                print(f"Running compose up for services: {services_list}")
-            docker.compose.up(detach=True, services=services_list)
+                print(f"Running compose up for extra_args: {extra_args_list}")
+            docker.compose.up(detach=True, services=extra_args_list)
         elif command == "down":
             if verbose:
                 print("Running compose down")
             docker.compose.down()
+        elif command == "exec":
+            if extra_args_list is None or len(extra_args_list) < 2:
+                print("Usage: exec <service> <cmd>")
+                sys.exit(1)
+            service_name = extra_args_list[0]
+            command_to_exec = extra_args_list[1:]
+            container_exec_env = {
+                "CERC_SCRIPT_DEBUG": "true"
+            } if debug else {}
+            if verbose:
+                print(f"Running compose exec {service_name} {command_to_exec}")
+            docker.compose.execute(service_name, command_to_exec, envs=container_exec_env)
+        elif command == "port":
+            if extra_args_list is None or len(extra_args_list) < 2:
+                print("Usage: port <service> <exposed-port>")
+                sys.exit(1)
+            service_name = extra_args_list[0]
+            exposed_port = extra_args_list[1]
+            if verbose:
+                print(f"Running compose port {service_name} {exposed_port}")
+            mapped_port_data = docker.compose.port(service_name, exposed_port)
+            print(f"{mapped_port_data[0]}:{mapped_port_data[1]}")
         elif command == "ps":
             if verbose:
                 print("Running compose ps")

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).
-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>`
+
+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
 ```

scripts/publish_shiv_package_github.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# Usage: publish_shiv_package_github.sh <major> <minor> <patch>
+# Uses this script package to publish a new release:
+# https://github.com/cerc-io/github-release-api
+# User must define: CERC_GH_RELEASE_SCRIPTS_DIR
+# pointing to the location of that cloned repository
+# e.g. 
+# cd ~/projects
+# git clone https://github.com/cerc-io/github-release-api
+# cd ./stack-orchestrator
+# export CERC_GH_RELEASE_SCRIPTS_DIR=~/projects/github-release-api
+# ./scripts/publish_shiv_package_github.sh
+# In addition, a valid GitHub token must be defined in
+# CERC_PACKAGE_RELEASE_GITHUB_TOKEN
+if [[ -z "${CERC_PACKAGE_RELEASE_GITHUB_TOKEN}" ]]; then
+    echo "CERC_PACKAGE_RELEASE_GITHUB_TOKEN is not set" >&2
+    exit 1
+fi
+# TODO: check args and env vars
+major=$1
+minor=$2
+patch=$3
+export PATH=$CERC_GH_RELEASE_SCRIPTS_DIR:$PATH
+github_org="cerc-io"
+github_repository="stack-orchestrator"
+latest_package=$(ls -1t ./package/* | head -1)
+uploaded_package="./package/laconic-so"
+# Remove any old package
+rm ${uploaded_package}
+cp ${latest_package} ${uploaded_package}
+github_release_manager.sh \
+        -l notused -t ${CERC_PACKAGE_RELEASE_GITHUB_TOKEN} \
+        -o ${github_org} -r ${github_repository} \
+        -d v${major}.${minor}.${patch} \
+        -c create -m "Release v${major}.${minor}.${patch}"
+github_release_manager.sh \
+        -l notused -t ${CERC_PACKAGE_RELEASE_GITHUB_TOKEN} \
+        -o ${github_org} -r ${github_repository} \
+        -d v${major}.${minor}.${patch} \
+        -c upload ${uploaded_package}

scripts/tag_new_release.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Usage: tag_new_release.sh <major> <minor> <patch>
+# Uses this script package to tag a new release:
+# User must define: CERC_GH_RELEASE_SCRIPTS_DIR
+# pointing to the location of that cloned repository
+# e.g. 
+# cd ~/projects
+# git clone https://github.com/cerc-io/github-release-api
+# cd ./stack-orchestrator
+# export CERC_GH_RELEASE_SCRIPTS_DIR=~/projects/github-release-api
+# ./scripts/publish_shiv_package_github.sh
+# TODO: check args and env vars
+major=$1
+minor=$2
+patch=$3
+export PATH=$CERC_GH_RELEASE_SCRIPTS_DIR:$PATH
+git_tag_manager.sh -M ${major} -m ${minor} -p ${patch} -t "Release ${major}.${minor}.${patch}"

setup.py

@@ -6,7 +6,7 @@ with open("requirements.txt", "r", encoding="utf-8") as fh:
     requirements = fh.read()
 setup(
     name='laconic-stack-orchestrator',
-    version='1.0.9',
+    version='1.0.12',
     author='Cerc',
     author_email='info@cerc.io',
     license='GNU Affero General Public License',

tests/smoke-test/run-smoke-test.sh

@@ -13,13 +13,15 @@ rm -rf $CERC_REPO_BASE_DIR
 mkdir -p $CERC_REPO_BASE_DIR
 # Pull an example small public repo to test we can pull a repo
 $TEST_TARGET_SO setup-repositories --include cerc-io/laconic-sdk
-# TODO: test building the repo into a container
-# Build two example containers
-# TODO: 
-$TEST_TARGET_SO build-containers --include cerc/builder-js,cerc/test-container
+# Test pulling a stack
+$TEST_TARGET_SO --stack test setup-repositories
+# Test building the a stack container
+$TEST_TARGET_SO --stack test build-containers
+# Build one example containers
+$TEST_TARGET_SO build-containers --include cerc/builder-js
 # Deploy the test container
-$TEST_TARGET_SO deploy-system --include test up
+$TEST_TARGET_SO --stack test deploy-system up
 # TODO: test that we can use the deployed container somehow
 # Clean up
-$TEST_TARGET_SO deploy-system --include test down
+$TEST_TARGET_SO --stack test deploy-system down
 echo "Test passed"