diff --git a/README.md b/README.md index 2cbc76e..78f9d8f 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ # Hot Pocket developer toolkit -Developer toolkit for Hot Pocket smart contract development. This toolkit makes use of Docker to provide a cross-platform development tools for developers. +Developer toolkit for Hot Pocket smart contract development. This toolkit makes use of Docker to provide a cross-platform development tools for developers. Using the toolkit, developers can spin-up local Hot Pocket clusters on their developer machines and test Hot Pocket smart contracts. We use Docker containers to run Hot Pocket and smart contracts in a Linux environment. We also use Docker containers to distribute developer tools so developers can use the tools on any platform as long as they install Docker. @@ -7,7 +7,7 @@ We use Docker containers to run Hot Pocket and smart contracts in a Linux enviro - [Docker](https://docs.docker.com/engine/install/) ## Docker build -Contains the docker image source files for cross-platform dev tools. +Docker image containing cross-platform cluster management scripts. ### Local build ``` @@ -28,8 +28,54 @@ Contains windows launcher scripts. Written using powershell and compiled to exe Install-Module ps2exe ``` +### Powershell script usage +```powershell +# Deploy contract to single-node cluster. +.\hpdevkit.ps1 deploy + +# Stop and cleanup everything (required for changing cluster size) +.\hpdevkit.ps1 clean + +# Use different cluster size. +$env:HP_CLUSTER_SIZE = 3 +.\hpdevkit.ps1 deploy + +# Look at specific node's logs. +.\hpdevkit.ps1 logs + +# Start/stop all nodes. +.\hpdevkit.ps1 start +.\hpdevkit.ps1 stop + +# Start/stop specific node. +.\hpdevkit.ps1 start +.\hpdevkit.ps1 stop +``` + +If the contract files directory also contains a file named `hp.cfg.override`, it will be used to override the hp.cfg of all nodes. This can be used to set contract specific parameters like 'bin_path' and 'bin_args' + +Example `hp.cfg.override` for a nodejs application: +``` +{ + "contract": { + "bin_path": "/usr/bin/node", + "bin_args": "app.js" + } +} +``` + ### Generate executable ```powershell cd windows Invoke-ps2exe .\hpdevkit.ps1 hpdevkit.exe ``` +The executable can be distributed to be run as a CLI tool on developer machine. + +## Environment variables +| Name | Description | Default value | +| --- | --- | --- | +| HP_CLUSTER | Name of the cluster. Can be used to spin up different clusters for different applications. | `default` | +| HP_CLUSTER_SIZE | Number of nodes in the cluster. Applied with 'deploy' command. | `1` | +| HP_DEFAULT_NODE | The node the 'deploy' command uses to display logs. | `1` | +| HP_DEVKIT_IMAGE | Docker image to be used for devkit cluster management. | `hpdevkit` | +| HP_INSTANCE_IMAGE | Docker image to be used for Hot Pocket instances. | `evernodedev/hotpocket:latest-ubt.20.04-njs.16` | \ No newline at end of file diff --git a/windows/hpdevkit.ps1 b/windows/hpdevkit.ps1 index 4ebcf16..14ea3bd 100644 --- a/windows/hpdevkit.ps1 +++ b/windows/hpdevkit.ps1 @@ -1,17 +1,18 @@ $GlobalPrefix = "hpdevkit" -$DevKitImage = "hpdevkit" -$VolumeMount = "/devkitvol" -$HotPocketImage = "evernodedev/hotpocket:latest-ubt.20.04-njs.16" $Cluster = if ($env:HP_CLUSTER) { $env:HP_CLUSTER } else { "default" }; $ClusterSize = if ($env:HP_CLUSTER_SIZE) { $env:HP_CLUSTER_SIZE } else { 1 }; $DefaultNode = if ($env:HP_DEFAULT_NODE) { $env:HP_DEFAULT_NODE } else { 1 }; +$DevKitImage = if ($env:HP_DEVKIT_IMAGE) { $env:HP_DEVKIT_IMAGE } else { "hpdevkit" }; +$InstanceImage = if ($env:HP_INSTANCE_IMAGE) { $env:HP_INSTANCE_IMAGE } else { "evernodedev/hotpocket:latest-ubt.20.04-njs.16" }; + +$VolumeMount = "/$($GlobalPrefix)_vol" $Volume = "$($GlobalPrefix)_$($Cluster)_vol" $Network = "$($GlobalPrefix)_$($Cluster)_net" $ContainerPrefix = "$($GlobalPrefix)_$($Cluster)_node" $BundleMount = "$($VolumeMount)/contract_bundle" -$DeploymentContainerName = "$($GlobalPrefix)_$($Cluster)_deploymanager" -$ConfigOverridesFile = "$($GlobalPrefix)_overrides.cfg" +$DeploymentContainerName = "$($GlobalPrefix)_$($Cluster)_deploymgr" +$ConfigOverridesFile = "hp.cfg.override" function DevKitContainer([string]$Mode, [string]$Name, [switch]$Detached, [switch]$AutoRemove, [switch]$MountSock, [switch]$MountVolume, [string]$Cmd) { @@ -26,15 +27,17 @@ function DevKitContainer([string]$Mode, [string]$Name, [switch]$Detached, [switc $Command += " --rm" } if ($MountSock) { + # We mount the host docker socket into the container so we can use it to issue commands to the docker host. + # We use this ability to spin up other containers (Hot Pocket nodes) on the host. $Command += " --mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock" } if ($MountVolume) { $Command += " --mount type=volume,src=$($Volume),dst=$($VolumeMount)" } - # Env variables. + # Pass environment variables used by our scripts. $Command += " -e CLUSTER=$($Cluster) -e CLUSTER_SIZE=$($ClusterSize) -e DEFAULT_NODE=$($DefaultNode) -e VOLUME=$($Volume) -e NETWORK=$($Network)" - $Command += " -e CONTAINER_PREFIX=$($ContainerPrefix) -e VOLUME_MOUNT=$($VolumeMount) -e BUNDLE_MOUNT=$($BundleMount) -e HOTPOCKET_IMAGE=$($HotPocketImage)" + $Command += " -e CONTAINER_PREFIX=$($ContainerPrefix) -e VOLUME_MOUNT=$($VolumeMount) -e BUNDLE_MOUNT=$($BundleMount) -e HOTPOCKET_IMAGE=$($InstanceImage)" $Command += " -e CONFIG_OVERRIDES_FILE=$($ConfigOverridesFile)" $Command += " $($DevKitImage)"