1
0
stack-orchestrator/docs/CONTRIBUTING.md
Marten O'Grady b1b1464205 Update CONTRIBUTING.md (#383)
Wrong output for Step 3 in Build A ZipApp.  Fixed it to what I just experienced while smoke testing.

Former-commit-id: bce604e4bb2823632adf809a1cadd228e5c017c3
2023-05-04 09:47:59 -04:00

3.1 KiB

Contributing

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 pre-requisites listed in the README, 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.10-venv
    

Install

  1. Clone this repository:

    $ git clone https://github.com/cerc-io/stack-orchestrator.git
    
  2. Enter the project directory:

    $ cd stack-orchestrator
    
  3. (This and the next step can be done by running source ./scripts/developer-mode-setup.sh)

    Create and activate a venv:

    $ python3 -m venv venv
    $ source ./venv/bin/activate
    (venv) $
    
  4. Install the cli in edit mode:

    $ pip install --editable .
    
  5. Verify installation:

    (venv) $ laconic-so
    Usage: laconic-so [OPTIONS] COMMAND [ARGS]...
    
     Laconic Stack Orchestrator
    
    Options:
     --quiet
     --verbose
     --dry-run
     -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...
    

Build a zipapp (single file distributable script)

Use shiv to build a single file Python executable zip archive of laconic-so:

  1. Install shiv:

    $ (venv) pip install shiv
    $ (venv) pip install wheel
    
  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:

  3. Verify it works:

    $ cp stack-orchetrator/laconic-so ~/bin
    $ laconic-so
       Usage: laconic-so [OPTIONS] COMMAND [ARGS]...
    
       Laconic Stack Orchestrator
    
    Options:
       --stack TEXT         specify a stack to build/deploy
       --quiet
       --verbose
       --dry-run
       --local-stack
       --debug
       --continue-on-error
       -h, --help           Show this message and exit.
    
    Commands:
       build-containers    build the set of containers required for a complete...
       build-npms          build the set of npm packages required for a...
       deploy              deploy a stack
       deploy-system       deploy a stack
       setup-repositories  git clone the set of repositories required to build...
       version             print tool version
    

For cutting releases, use the shiv build script.