Oracle Blockchain Platform Digital Assets Edition allows the generation of wrapper APIs for all controller APIs within App Builder generated chaincode. This topic provides detailed steps for deploying the wrapper APIs package in the stack resource manager and testing the wrapper APIs using the associated Postman collection.

1. Log in to OCI.
   Open the OCI console and sign in: https://cloud.oracle.com/.
   Ensure you're in the compartment where the stack will be deployed.
2. Expand the Navigation menu. Select Developer Services. Under Resource Manager, select Stacks.
   The Resource Manager interface for stacks opens. You can view existing stacks, create new stacks, and manage your infrastructure as code using Terraform configurations.
3. Create a new stack by clicking Create Stack.
4. Configure the stack information.
   1. In the Terraform Configuration section, select My Configuration.
   2. In Stack Configuration, Terraform configuration source, select .Zip file.
   3. Click Browse and navigate to your wrapper APIs Zip file.
   4. Once it's uploaded, ensure the stack name is correct.
   5. All remaining settings can be kept as default. Click Next.
5. Configure the stack variables.
   1. Verify that all configuration variable values are accurate and align with the configuration variables specified in the wrapper API package to meet the requirements for your deployment.
   2. For ocir_user_name, enter the email address associated with your OCI account.
   3. For ocir_user_password enter your password, which is your Oracle Cloud Infrastructure Auth Token. This token can be generated in the OCI console under your user settings. The Auth Token serves as a password for logging into the Oracle Cloud Infrastructure Registry (OCIR).
      For detailed instructions on generating the Auth Token, refer to Generating an Auth Token.
   4. All remaining settings can be kept as default. Click Next.
6. Review the stack information. If everything is correct, click Create.
7. Execute the Terraform plan.
   1. On the stack's Details page, click Plan to initiate the creation of an execution plan.
   2. Optionally configure the job plan. You can edit the default name or select advanced options to change provider version of adjust settings.
   3. Click Plan to create and run the plan job.
      This will parse your Terraform configuration, generate an execution plan, and execute the plan which does the following:

      • Validates the Terraform script to ensure there are no syntax or configuration errors.
      • Simulates the resource creation process without making any changes to the actual infrastructure.
      • Provides an output summary that lists the resources the script intends to create, modify, or destroy.
   4. Monitor the status in the Jobs section of your stack. Once the plan completes successfully, review the output to confirm the number of resources that will be created and verify that there are no issues.
8. Apply the Terraform plan to the stack.
   1. On the stack's Details page, click Apply.
   2. In the Terraform Apply panel, click Apply.
      This will do the following:

      • Provisions all of the following resources as defined in the Terraform script:
        • Virtual cloud network (VCN)
        • Applications (OCI Functions)
        • API Gateway
        • API deployment
        • IAM Policy
        • OCI Registry repository
      • Creates all the required infrastructure for the Wrapper APIs.
   3. Monitor the status in the Jobs section of your stack to ensure the job completed successfully with no errors.
9. Retrieve the API Gateway endpoints.
   1. Once the Apply job has finished, go to the Outputs section of the Apply job page to view the generated output values.
   2. The output will return a JSON object where the keys represent endpoint names and the values are their corresponding endpoint values.
      For example:

      api_gateway_endpoints{"api_gateway_endpoint":"https://grqkdiwsugp3fp2m5z3zgpo4.apigateway.ap-mumbai-1.oci.customer-oci.com/WholesaleCBDC"}

   3. Copy the endpoint - it's needed to updating the API Postman collection.

Testing Wrapper APIs with Postman

You can test the APIs in Postman. Configure all the variables in the wrapper API Postman collection by assigning the appropriate values. The api_gateway_endpoint value must be obtained from the output of the stack deployment in OCI, where the dynamically generated gateway endpoints will be provided.

Once the variables in the Postman collection have been updated, you can test the wrapper APIs. Each API request in the collection includes the necessary payload specific to the corresponding wrapper API.

Figure 6-1 Testing an API Wrapper Collection with Postman

Troubleshooting

The following are some commonly encountered issues and their solutions.

Unauthorized: Invalid ocir_user_name or ocir_user_password

This error occurs when either the username or password credentials are incorrect. To resolve this issue, follow these steps:

1. Navigate to the Variables section in the stack Details page.
2. Click Edit Variables to modify the username and password values.
3. Update the credentials with the correct information.
4. Once the changes are made, click Apply to redeploy the stack.

This should resolve the authentication issue and allow the deployment to proceed successfully.

Deployment Failure - "denied: Anonymous users are only allowed read access on public repos"

Occasionally, the deployment might fail with the following error:

denied: Anonymous users are only allowed read access on public repos

This is an intermittent issue that is related to Docker operations within the stack's backend. Specifically, this error occurs when attempting to push Docker images to the Oracle Cloud Infrastructure Registry (OCIR) without proper authentication.

While the wrapper API package includes a script that performs docker login before pushing the images, ensuring proper authentication, this error can still occur sporadically. It typically happens when the Docker authentication step is not properly recognized by the system at the time of image push.

If this error occurs, follow these steps to resolve the issue:

1. Destroy Existing Resources:

   Click Destroy in the OCI Stack Resource Manager to destroy all the resources created during the deployment process.

2. Reapply the Stack:

   After destroying the resources, click Apply again to redeploy the stack. This will trigger the creation of the necessary resources, including proper Docker authentication, and should resolve the issue.

Generic Deployment Failure: Intermittent Issues

Sometimes, stack deployment may fail due to random like docker related issues. In such cases, follow these steps to resolve the issue:

1. Click Destroy to remove all the resources created during the failed deployment.
2. Once the resources are destroyed, navigate back to the stack and click Apply to redeploy the stack.

This process often resolves intermittent issues, allowing the deployment to proceed successfully.