diff --git a/dev/local-environment/README.md b/dev/local-environment/README.md index c1ed8ecb7..9c4cf3db8 100644 --- a/dev/local-environment/README.md +++ b/dev/local-environment/README.md @@ -1,6 +1,8 @@ # Partner Chains Local Environment -This stack is designed to run a 5 x Partner Chains node local environment for a partnerchain. It is based on the custom IO Substrate image. +This stack is designed to run a 5 x Partner Chains node local environment for a partner chain. It is based on the custom IO Substrate image. + +![alt text](pc-local-env.png) The local environment includes: @@ -14,31 +16,23 @@ The local environment includes: The stack `setup.sh` script will create a docker-compose.yml stack configuration files, and populate an .env file with environment values. The stack can be deployed with `docker-compose up -d`. -When first run, all images will be pulled from public repositories. This stage may take some time. The stack will then be built and run. - -When the stack is running, the 3 Cardano nodes will peer and being block production. This is a private testnet and will not connect to the public Cardano network, but rather from a pre-configured genesis file. - -Once the Cardano chain is synced, Ogmios, Kupo and DB-Sync will in turn connect to the Cardano node node.socket and begin syncing the chain. +## Local env - step by step -The pc-contracts-cli will insert D parameter values and register Partner Chains Node keys with the Cardano chain. +- When first run, all images will be pulled from public repositories. This stage may take some time. The stack will then be built and run. +- When the stack is running, the 3 Cardano nodes will peer and being block production. This is a private testnet and will not connect to the public Cardano network, but rather from a pre-configured genesis file. +- Once the Cardano chain is synced, Ogmios, Kupo and DB-Sync will in turn connect to the Cardano node node.socket and begin syncing the chain. +- The pc-contracts-cli will insert D parameter values and register Partner Chains Node keys with the Cardano chain. +- Once Postgres is populated with the required data, the Partner Chains nodes will begin syncing the chain and will begin block production after 2 main chain epochs. -Once Postgres is populated with the required data, the Partner Chains nodes will begin syncing the chain and will begin block production after 2 main chain epochs. +## Initialising the environment configuration -## Configuring the environment - -Run `setup.sh` script to create the environment .env values and docker-compose.yml +Run `setup.sh` script to enter the setup wizard for initialising the environment .env values and docker-compose.yml. The `setup.sh` script also support a `--non-interactive` flag to accept default configuration settings, or configuration elements can be specified directly with args (see `--help` for details) ``` chmod +x setup.sh bash setup.sh` ``` -The `setup.sh` script also support a `--non-interactive` flag to accept default configuration settings, and some additional arguments to set configuration values directly. See the help page for more information - -``` -bash setup.sh --help -``` - ## Starting the environment Once initialized, deploy the local environment from .env values with the following: @@ -57,8 +51,47 @@ When stopping the stack, it is mandatory to also wipe all volumes. The environme docker compose down --volumes ``` -## Using custom node image +## Custom Images and Artifacts + +To use custom node image one simply has to update `PARTNER_CHAINS_NODE_IMAGE` (docker image) and `PARTNER_CHAINS_NODE_URL` (node artifact, used to build chain-spec and generate signatures for SPO registration) + +These can be found at the very top of the `setup.sh` script. + +Make sure that `PC_CONTRACTS_CLI_ZIP_URL` version is compatible with your custom node. -To use custom node image one simply has to update `PARTNER_CHAINS_NODE_IMAGE` (docker image) and `PARTNER_CHAINS_NODE_URL` (node artifact, used to build chain-spec and generate signatures for SPO registration) in `setup.sh` script. +Alternatively artifact URLs can be overriden from local files with the `--overrides` argument. See main `setup.sh` interactive dialogue for more details. -Also, make sure that `PC_CONTRACTS_CLI_ZIP_URL` version is compatible with your custom node. +``` +cd dev/local-environment +cp /path/to/artifact ./configurations/pc-contracts-cli/overrides/partner-chains-cli +cp /path/to/artifact ./configurations/pc-contracts-cli/overrides/partner-chains-node +bash setup.sh --non-interactive --overrides --node-image ${{ inputs.image }} +``` + +## Custom Deployment Options + +The `setup.sh` script supports argument `--deployment-option X` with the below possible options: + +1. Include only Cardano testnet +2. Include Cardano testnet with Kupo and Ogmios +3. Include Cardano testnet, Kupo, Ogmios, DB-Sync and Postgres +4. Deploy a single Partner Chains node with network_mode: "host" for external connections + +Option 3 is suitable for providing a local Postgres with our minimal Cardano chain for local testing. Option 4 is suitable for deploying individual Partner Chain Nodes accross distrubted systems. + +## Other Features + +We are continuing to develop this utility for a range of appications, and regularly add additional features. The `setup.sh --help` output will always show the latest details for available features: + +``` +$ bash setup.sh --help +Usage: setup.sh [OPTION]... +Initialize and configure the Docker environment. + -n, --non-interactive Run with no interactive prompts and accept sensible default configuration settings. + -d, --deployment-option Specify one of the custom deployment options (1, 2, 3, or 4). + -p, --postgres-password Set a specific password for PostgreSQL (overrides automatic generation). + -o, --overrides Enable custom artifact overrides from artifacts in ./configurations/pc-contracts-cli/ (PC and PCSC). + -i, --node-image Specify a custom Partner Chains Node image. + -t, --tests Include tests container. + -h, --help Display this help dialogue and exit. +``` diff --git a/dev/local-environment/pc-local-env.png b/dev/local-environment/pc-local-env.png new file mode 100644 index 000000000..8130a5e55 Binary files /dev/null and b/dev/local-environment/pc-local-env.png differ