Script and readme cleanup.

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 <contract files directory>
+
+# Stop and cleanup everything (required for changing cluster size)
+.\hpdevkit.ps1 clean
+
+# Use different cluster size.
+$env:HP_CLUSTER_SIZE = 3
+.\hpdevkit.ps1 deploy <contract files directory>
+
+# Look at specific node's logs.
+.\hpdevkit.ps1 logs <node number>
+
+# Start/stop all nodes.
+.\hpdevkit.ps1 start
+.\hpdevkit.ps1 stop
+
+# Start/stop specific node.
+.\hpdevkit.ps1 start <node number>
+.\hpdevkit.ps1 stop <node number>
+```
+
+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` |

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)"