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.
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
.
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:
Create an application and transfer the generated App ID into the
.env
file.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).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.Subscription
: Choose the appropriate message subscriptions for your moduleunique.chat.user-message.created
: This event is triggered with each user interaction.unique.chat.external-module.chosen
: This event is triggered when an external module is selected.
Next, extract the signing secret from the endpoint you created and insert it into the
.env
file.
Activate the application by selecting the 'Activate' button.
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.
The final element to complete the
.env
file is theAPI_BASE
parameter, which varies based on the deployment environment.For Unique Next, use the following URL:
https://gateway.unique.app/public/chat-gen2
.For Single Tenant deployments:
https://gateway.{NAME}.unique.app/public/chat
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 Policy – Terms of Service