Deployment of Hosted SDK Module

Important: The deployment of modules explained in this page is only applicable for customers with Hosted SDK, which is a paid feature. Refer to Hosted SDK to learn about upselling or co-development opportunities. Details about the Unique SDK can be found here.

 

This guide explains step-by-step the deployment process for client modules created using the Unique SDK . The following example illustrates how to deploy a module called assistant_demo to the Unique Next environment, which is the Unique multi-tenant setup.

1. Repository Cloning

Customers with a Hosted SDK Hosted SDK will be given access to a dedicated GitHub repo for the deployment of modules. Please contact the platform provisioners of Unique in case you need more details regarding this.

2. Incorporating your SDK Module

Add your module by creating a new directory within the repository (for example, assistant_demo). Adhere to the instructions and prerequisites outlined in the README.md 's second step. Each module maintains its own isolated poetry project and operates independently from other modules. Ensure that you only include essential dependencies.

image-20240417-110701.png

app.py:

This is the primary executable for the Flask application and must reside in a subdirectory that shares its name with the root directory. Critical Notes:

  • The file app.py must implement webhook signature verification for security purposes.

  • Modify the import path specified in the __init__.py file located within the same directory.

.flaskenv:

This is the Flask environment configuration file. Update the application path accordingly (in this case, FLASK_APP=assistant_demo/app.py).

poetry.lock & pyproject.toml:

These files define the precise dependencies your module requires.

.env & .env.enc:

These files store the credentials necessary for connecting to the Unique platform. Detailed configuration instructions are provided below.

3. Configuration of Environment Files

Each module is equipped with a dedicated .env configuration file, as outlined in step 3 of the this README.md . For instances where a module is operational across multiple environments, such as QA and Production, a distinct .env file is required for each setting. Adhere to the following format when naming the environment file for e.g. QA: .qa.env.

image-20240417-111816.png

To procure the necessary credentials for these environment files, you must first establish an application within the relevant environment (here next). The subsequent steps will guide you through this process:

  1. Create an application and transfer the generated App ID into the .env file.

  2. Set up an endpoint, initially using a placeholder URL (here dummy). Post-deployment of the Azure container app, you will replace this placeholder with the actual URL (details provided further in this guide).

    1. In Development: Ensure you check the box only if the module is still under development. Strictly avoid doing so for modules that are live in production.

    2. Subscription: Choose the appropriate message subscriptions for your module

      1. unique.chat.user-message.created: This event is triggered with each user interaction.

      2. unique.chat.external-module.chosen: This event is triggered when an external module is selected.

  1. Next, extract the signing secret from the endpoint you created and insert it into the .env file.

  1. Activate the application by selecting the 'Activate' button.

  2. Generate an API key and incorporate it into the .env file.

    Note: You will only be able to view the API key once upon creation. If misplaced, you must generate a new one.

  1. The final element to complete the .env file is the API_BASE parameter, which varies based on the deployment environment.

    1. For Unique Next, use the following URL: https://gateway.unique.app/public/chat-gen2.

    2. For Single Tenant deployments: https://gateway.{NAME}.unique.app/public/chat

    3. For alternative deployments, please consult Unique.

4. Encryption of the Environment File

Generate a encrypted version of your environment file, named .env.enc, using your public encryption key. If you do not possess the key, reach out to Unique for assistance. Refer to the README.md step 3 for detailed instructions.

The contents of the encrypted file should mirror the following format:

5. GitHub Workflow Configuration

To set up a GitHub workflow, follow the instruction provided in step 4 of the README.md. It is essential to create individual workflows for each module and environment (e.g. one flow for QA and one for PROD).

Ensure you have reviewed all supplementary information concerning GitHub workflows and Docker files as mentioned in the README.md.

Important: Verify that the workflow parameters, namely environment, module, and encrypted_env_file, are correctly updated to match the module and environment being deployed.

6. Deployment of Azure Container App

Upon integrating the new module into the main branch, new workflows will be accessible under the 'Actions' tab on GitHub. Execute the relevant workflow to initiate the deployment of the Azure Container App.

After successful deployment, the deployment summary will provide the URL needed for the endpoint configuration.

7. Update Endpoint

Replace the endpoint URL on the Unique platform with the one generated from the deployment summary.

Important:

  • The URL must to start with https://

  • Append the suffix /webhook to the container URL

8. Assistant

With the deployment complete, your new module is now ready for integration into an assistant.

 


Author

@Fabian Schläpfer

© 2024 Unique AG. All rights reserved. Privacy PolicyTerms of Service