Update instructions for onboarding-api stack (#5)

Part of [laconicd testnet validator enrollment](https://www.notion.so/laconicd-testnet-validator-enrollment-6fc1d3cafcc64fef8c5ed3affa27c675)

Reviewed-on: #5
Co-authored-by: Prathamesh Musale <prathamesh.musale0@gmail.com>
Co-committed-by: Prathamesh Musale <prathamesh.musale0@gmail.com>

stack-orchestrator/stacks/onboarding-api/README.md

@@ -2,18 +2,28 @@
 
 Instructions for running the `testnet-onboarding-api` using [laconic-so](https://git.vdb.to/cerc-io/stack-orchestrator)
 
+## Prerequisite
+
+* `laconic-so`: [installation](https://git.vdb.to/cerc-io/stack-orchestrator#install) instructions
+* sumsub application token: <https://docs.sumsub.com/docs/app-tokens>
+
 ## Setup
 
-* Clone the stack repo:
+* Fetch the stack repo:
 
   ```bash
   laconic-so fetch-stack git.vdb.to/cerc-io/testnet-onboarding-app-stack
   ```
 
+  This should clone the stack repo in `$HOME/cerc` directory
+
 * Setup required repositories:
 
   ```bash
-  laconic-so --stack ~/cerc/testnet-onboarding-app-stack/stack-orchestrator/stacks/onboarding-api setup-repositories
+  laconic-so --stack ~/cerc/testnet-onboarding-app-stack/stack-orchestrator/stacks/onboarding-api setup-repositories --pull
+
+  # If this throws an error as a result of being already checked out to a branch/tag in a repo, remove the repositories and re-run the command
+  # The repositories are located in $HOME/cerc by default
   ```
 
 * Build the container image:
@@ -22,34 +32,31 @@ Instructions for running the `testnet-onboarding-api` using [laconic-so](https:/
   laconic-so --stack ~/cerc/testnet-onboarding-app-stack/stack-orchestrator/stacks/onboarding-api build-containers
   ```
 
-  This should create the `cerc/testnet-onboarding-api` image locally
+  This should create the `cerc/testnet-onboarding-api` Docker image locally, same can be confirmed by running `docker image ls`
 
 ## Create a deployment
 
 * Create a spec file for the deployment:
 
   ```bash
-  laconic-so --stack ~/cerc/testnet-onboarding-app-stack/stack-orchestrator/stacks/onboarding-api deploy init --output onboarding-api-spec.yml
+  laconic-so --stack ~/cerc/testnet-onboarding-app-stack/stack-orchestrator/stacks/onboarding-api deploy init --map-ports-to-host any-same --output onboarding-api-spec.yml
   ```
 
-* Edit `network` in the spec file to map container ports to host ports as required:
+  * This should create the spec file `onboarding-api-spec.yml`
+  * The port mapping option `any-same` binds the ports for Docker services to `0.0.0.0` on the host machine; edit the spec file to change the mapping as desired
 
-  ```bash
-  network:
-    ports:
-      testnet-onboarding-api:
-        - '3000:3000'
-  ```
-
-* Create a deployment from the spec file:
+* Create an `onboarding-api` stack deployment from the spec file:
 
   ```bash
   laconic-so --stack ~/cerc/testnet-onboarding-app-stack/stack-orchestrator/stacks/onboarding-api deploy create --spec-file onboarding-api-spec.yml --deployment-dir onboarding-api-deployment
   ```
 
+  * This should create the deployment directory `onboarding-api-deployment`
+  * Note: Once a deployment is created from the spec file, the port mappings are set in Docker compose files; in order to change the port mapping after that, the deployment has to be re-created with a modified spec file
+
 ## Configuration
 
-* Inside the `onboarding-api-deployment` deployment directory, open `config.env` file and set following env variables:
+* Inside the `onboarding-api-deployment` deployment directory, open `config.env` and set following env variables:
 
   ```bash
   # Your sumsub application token
@@ -60,10 +67,10 @@ Instructions for running the `testnet-onboarding-api` using [laconic-so](https:/
 
   # Optional
 
-  # KYC level of access token being generated (default: basic-kyc-level)
+  # Default KYC level of access token being generated (default: basic-kyc-level)
   KYC_LEVEL=
 
-  # TTL for the generated access token in seconds (default: 600)
+  # Default TTL for the generated access token in seconds (default: 600)
   TTL_IN_SECS=
   ```
 
@@ -78,14 +85,15 @@ Instructions for running the `testnet-onboarding-api` using [laconic-so](https:/
 * To list down and monitor the running container:
 
   ```bash
-  # With status
   docker ps
 
+  # Ensure that the testnet-onboarding-api container is healthy
+
   # Check logs for the server
   laconic-so deployment --dir onboarding-api-deployment logs -f testnet-onboarding-api
   ```
 
-## Run
+## Example
 
 * Generate an access token for a user:
 
@@ -95,7 +103,7 @@ Instructions for running the `testnet-onboarding-api` using [laconic-so](https:/
     -d '{"userId": "JamesBond007"}'
 
   # Expected output:
-  # {"token":"generated-access-token"}
+  # {"token":"<generated-access-token>"}
   ```
 
 ## Clean up

stack-orchestrator/stacks/onboarding-api/stack.yml

@@ -2,7 +2,7 @@ version: "1.0"
 name: onboarding-api
 description: "Testnet onboarding API"
 repos:
-  - git.vdb.to/cerc-io/testnet-onboarding-api
+  - git.vdb.to/cerc-io/testnet-onboarding-api@v0.1.0
 containers:
   - cerc/testnet-onboarding-api
 pods: