Update instructions for onboarding-api stack

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`
+
 * Setup required repositories:
 
   ```bash
   laconic-so --stack ~/cerc/testnet-onboarding-app-stack/stack-orchestrator/stacks/onboarding-api setup-repositories
+
+  # 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
@@ -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