Merge pull request #49 from cerc-io/dboreham/laconicd-landing-page

Add laconicd fixturenet readme

README.md

@@ -3,29 +3,18 @@
 Stack Orchestrator allows building and deployment of a Laconic stack on a single machine with minimial prerequisites.
 
 ## Setup
-### Developer Mode
-Developer mode runs the orchestrator from a cloned git repository.
+### User Mode
+User mode runs the orchestrator from a "binary" single-file release and does not require special Python environment setup. Use this mode unless you plan to make changes to the orchestrator source code.
 #### Prerequisites
 Stack Orchestrator is a Python3 CLI tool that runs on any OS with Python3 and Docker. Tested on: Ubuntu 20/22.
 
 Ensure that the following are already installed:
 
-1. Python3 (the version 3.8 available in Ubuntu 20/22 works)
+1. Python3 (the stock Python3 version available in Ubuntu 20 and 22 is suitable)
    ```
    $ python3 --version
    Python 3.8.10
    ```
-1. Python venv package
-   This may or may not be already installed depending on the host OS and version. Check by running:
-   ```
-   $ python3 -m venv
-   usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear] [--upgrade] [--without-pip] [--prompt PROMPT] ENV_DIR [ENV_DIR ...]
-   venv: error: the following arguments are required: ENV_DIR
-   ```
-   If the venv package is missing you should see a message indicating how to install it, for example with:
-   ```
-   $ apt install python3.8-venv
-   ```
 2. Docker (Install a current version from dockerco, don't use the version from any Linux distro)
    ```
    $ docker --version
@@ -42,6 +31,47 @@ Ensure that the following are already installed:
    # or to install for all users.
    ```
 #### Install
+1. Download the latest release from [this page](https://github.com/cerc-io/stack-orchestrator/tags), into a suitable directory (e.g. `~/bin`):
+   ```
+   $ cd ~/bin
+   $ curl https://github.com/cerc-io/stack-orchestrator/releases/download/v1.0.0-alpha/laconic-so
+   ```
+1. Ensure `laconic-so` is on the `PATH`
+1. Verify operation:
+   ```
+   $ ~/bin/laconic-so --help
+   Usage: python -m laconic-so [OPTIONS] COMMAND [ARGS]...
+
+     Laconic Stack Orchestrator
+
+   Options:
+     --quiet
+     --verbose
+     --dry-run
+     --local-stack
+     -h, --help     Show this message and exit.
+
+   Commands:
+     build-containers    build the set of containers required for a complete...
+     deploy-system       deploy a stack
+     setup-repositories  git clone the set of repositories required to build...
+   ```
+### 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:
+1. Python venv package
+   This may or may not be already installed depending on the host OS and version. Check by running:
+   ```
+   $ python3 -m venv
+   usage: venv [-h] [--system-site-packages] [--symlinks | --copies] [--clear] [--upgrade] [--without-pip] [--prompt PROMPT] ENV_DIR [ENV_DIR ...]
+   venv: error: the following arguments are required: ENV_DIR
+   ```
+   If the venv package is missing you should see a message indicating how to install it, for example with:
+   ```
+   $ apt install python3.8-venv
+   ```
+#### Install
 1. Clone this repository:
    ```
    $ git clone (https://github.com/cerc-io/stack-orchestrator.git
@@ -78,11 +108,13 @@ Ensure that the following are already installed:
     deploy-system       deploy a stack
     setup-repositories  git clone the set of repositories required to build...
    ```
+
 #### 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:
    ```

app/setup_repositories.py

@@ -22,6 +22,7 @@ from decouple import config
 import git
 from tqdm import tqdm
 import click
+from .util import include_exclude_check
 
 
 class GitProgress(git.RemoteProgress):
@@ -49,11 +50,13 @@ def is_git_repo(path):
 
 
 @click.command()
+@click.option("--include", help="only clone these repositories")
+@click.option("--exclude", help="don\'t clone these repositories")
 @click.option('--check-only', is_flag=True, default=False)
 @click.option('--pull', is_flag=True, default=False)
 @click.option('--branches-file', help="checkout branches specified in this file")
 @click.pass_context
-def command(ctx, check_only, pull, branches_file):
+def command(ctx, include, exclude, check_only, pull, branches_file):
     '''git clone the set of repositories required to build the complete system from source'''
 
     quiet = ctx.obj.quiet
@@ -87,10 +90,18 @@ def command(ctx, check_only, pull, branches_file):
         os.makedirs(dev_root_path)
 
     with open("repository-list.txt") as repository_list_file:
-        repos = repository_list_file.read().splitlines()
+        all_repos = repository_list_file.read().splitlines()
 
     if verbose:
-        print(f'Repos: {repos}')
+        print(f'Repos: {all_repos}')
+
+    repos = []
+    for repo in all_repos:
+        if include_exclude_check(repo, include, exclude):
+            repos.append(repo)
+        else:
+            if not quiet:
+                print(f"Excluding: {repo}")
 
     def process_repo(repo):
         full_github_repo_path = f'git@github.com:{repo}'

stacks/laconicd/README.md

@@ -0,0 +1,19 @@
+# Laconicd Fixturenet
+
+Instructions for deploying a local Laconic blockchain "fixturenet" for development and testing purposes using laconic-stack-orchestrator (the installation of which is covered [here](https://github.com/cerc-io/stack-orchestrator#install)):
+
+## Clone required repositories
+```
+$ laconic-so setup-repositories --include cerc-io/laconicd,cerc-io/laconic-sdk,cerc-io/laconic-cns-cli
+```
+## Build the laconicd container
+```
+$ laconic-sh build-containers --include cerc/laconicd
+```
+This should create a container with tag `cerc/watcher-mobymask` in the local image registry.
+## Deploy the stack
+First the watcher database has to be initialized. Start only the watcher-db service:
+```
+$ laconic-so deploy-system --include fixturenet-laconicd
+```
+Correct operation should be verified by checking the laconicd container's log.

stacks/laconicd/stack.yml

@@ -0,0 +1,11 @@
+version: "1.0"
+name: laconicd-fixturenet
+repos:
+  - cerc-io/laconicd
+  - cerc-io/laconic-sdk
+  - cerc-io/laconic-cns-cli
+containers:
+  - cerc/laconicd
+  - cerc/laconic-cns-cli
+pods:
+  - fixturenet-laconicd

stacks/mobymask/README.md

@@ -8,7 +8,7 @@ The instructions below show how to deploy a MobyMask watcher using laconic-stack
 This deployment expects that ipld-eth-server's endpoints are available on the local machine at http://ipld-eth-server.example.com:8083/graphql and http://ipld-eth-server.example.com:8082. More advanced configurations are supported by modifying the watcher's [config file](../../config/watcher-mobymask/mobymask-watcher.toml).
 ## Clone required repositories
 ```
-$ laconic-so setup-repositories
+$ laconic-so setup-repositories --include vulcanize/assemblyscript,cerc-io/watcher-ts
 ```
 Checkout required branches for the current release:
 ```