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

# onboarding-api

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

* 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 --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:

  ```bash
  laconic-so --stack ~/cerc/testnet-onboarding-app-stack/stack-orchestrator/stacks/onboarding-api build-containers
  ```

  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 --map-ports-to-host any-same --output onboarding-api-spec.yml
  ```

  * 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

* 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` and set following env variables:

  ```bash
  # Your sumsub application token
  SUMSUB_APP_TOKEN=

  # Your sumsub secret key
  SUMSUB_SECRET_KEY=

  # Optional

  # Default KYC level of access token being generated (default: basic-kyc-level)
  KYC_LEVEL=

  # Default TTL for the generated access token in seconds (default: 600)
  TTL_IN_SECS=
  ```

## Start the deployment

  ```bash
  laconic-so deployment --dir onboarding-api-deployment start
  ```

## Check status

* To list down and monitor the running container:

  ```bash
  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
  ```

## Example

* Generate an access token for a user:

  ```bash
  curl -X POST http://localhost:3000/generate-token \
    -H "Content-Type: application/json" \
    -d '{"userId": "JamesBond007"}'

  # Expected output:
  # {"token":"<generated-access-token>"}
  ```

## Clean up

* Stop the deployment:

  ```bash
  laconic-so deployment --dir onboarding-api-deployment stop
  ```