Deployment Guide: Semantic Kernel Health Assistant on Azure App Service

This guide provides instructions for deploying the Semantic Kernel Health Assistant application, built with Chainlit and Python, to Azure App Service using code from a private GitHub repository.

Overview

The application leverages Semantic Kernel, Azure OpenAI Agents, Chainlit for the UI, and various plugins for health-related tasks (fitness, nutrition, mental care). It interacts with external services (like Gmail via SMTP) and uses Playwright for web scraping. This guide focuses on deploying it as an Azure Web App on Linux.

Prerequisites

Azure Account: An active Azure subscription.
Azure CLI (Optional): Installed and configured (Install Guide) OR access to the Azure Portal.
Git: Installed locally.
GitHub Account: Access to the private GitHub repository containing the application code.
Application Code:
- Code pushed to the private GitHub repository.
- A requirements.txt file listing all Python dependencies in the repository root.
- Your main Chainlit application script (e.g., app.py) in the repository root.
- (Recommended) A runtime.txt file specifying the Python version (e.g., python-3.11) in the repository root.

Setup & Configuration Files

Ensure the following files are correctly configured in your GitHub repository:

requirements.txt:

Must include chainlit, semantic-kernel, python-dotenv, azure-identity, openai, pytube, playwright, requests, pytz, icalendar (or ics), and any other libraries your agents and plugins use.
Make sure versions are specified for stability (e.g., chainlit==1.0.0).

Example:

chainlit==<your_version>
semantic-kernel==<your_version>
python-dotenv==<your_version>
azure-identity==<your_version>
openai==<your_version> # Check compatibility with SK/Azure Agents
pytube==<your_version>
playwright==<your_version>
requests==<your_version>
pytz==<your_version>
icalendar==<your_version>
# Add any other dependencies...

runtime.txt (Recommended):
- Specifies the Python version for Azure App Service. Create this file in the root directory.
- Example content:
```
python-3.11
```
.env File (Local Development Only):
- This file contains your secrets (API keys, Assistant IDs, email credentials) for local testing only.
- DO NOT COMMIT THIS FILE TO GIT. Add .env to your .gitignore file.
- All variables defined here will need to be added to the Azure App Service Application Settings during deployment.
app.py (or your main script):
- This should be the entry point for your Chainlit application, the script targeted by the chainlit run command.
- Ensure any file paths used (especially for the SQLite database) are suitable for a Linux environment.
Plugin Paths (SQLite Database):
- Your plugins HealthManagerPlugin and UserProfileQueryPlugin use data/memory.db. In Azure App Service, file system writes outside of /home are often ephemeral or restricted.
- Modify the plugin code to use a path within /home, which offers persistent storage (for the lifetime of the App Service Plan instance, unless using mounted storage).
- Example change in HealthManagerPlugin and UserProfileQueryPlugin:
```
# In __init__ method of both plugins
# self.db_path = "data/memory.db" # Old relative path
self.db_path = "/home/data/memory.db" # New absolute path

# Ensure the directory exists before connecting (add this logic if needed)
import os
db_dir = os.path.dirname(self.db_path)
if not os.path.exists(db_dir):
     os.makedirs(db_dir) 
     print(f"Created directory: {db_dir}")
```
- The startup command will later ensure the Playwright browsers are installed.

Deployment Steps (Using Azure Portal)

Create Azure App Service:
- Log in to the Azure Portal.
- Click + Create a resource.
- Search for and select Web App. Click Create.
- Basics Tab:
  - Subscription: Select your Azure subscription.
  - Resource Group: Choose an existing or create a new one.
  - Name: Enter a globally unique name for your web app (e.g., my-health-assistant-app). This becomes part of the URL (<name>.azurewebsites.net).
  - Publish: Select Code.
  - Runtime stack: Select Python 3.x (choose the version matching your runtime.txt or development environment, e.g., Python 3.11).
  - Operating System: Select Linux.
  - Region: Choose a region close to you or your users.
  - App Service Plan: Choose an existing Linux plan or create a new one (e.g., using the B1 Basic pricing tier as a start).
- Click Review + create, verify the settings, and click Create. Wait for the deployment to complete.
Configure Deployment from GitHub:
- Go to the newly created App Service resource.
- In the left menu, navigate to Deployment -> Deployment Center.
- Settings Tab:
  - Source: Select GitHub.
  - GitHub Account: Authorize Azure to access your GitHub account if prompted.
  - Organization: Select the organization or user owning the repository.
  - Repository: Select your private repository.
  - Branch: Select the branch you want to deploy (e.g., main or master).
  - The Runtime stack and Version should reflect your choices during App Service creation.
- Click Save. This configures a GitHub Actions workflow (.github/workflows/) in your repository to automatically build and deploy your app on pushes to the selected branch. The first deployment will start automatically.
Configure Application Settings (Environment Variables):
- While the first deployment runs, go to Settings -> Configuration in the App Service menu.
- Select the Application settings tab.
- Click + New application setting for each variable currently in your local .env file.
  - Name: Must exactly match the environment variable name used in your Python code (e.g., AZURE_OPENAI_API_KEY, GMAIL_SENDER_EMAIL, GMAIL_APP_PASSWORD, FITNESS_ASSISTANT, etc.).
  - Value: Enter the corresponding secret value.
  - Leave "Deployment slot setting" unchecked unless you are using deployment slots.
- Click OK after adding each setting.
- Important: After adding all settings, click Save at the top of the Configuration page and Continue when prompted to restart the app.
Configure Managed Identity (Recommended for Azure Services):
- If using DefaultAzureCredential to access Azure services (like Azure OpenAI):
  - Go to Settings -> Identity.
  - Select the System assigned tab.
  - Toggle Status to On.
  - Click Save and confirm Yes.
  - Once enabled, click on Azure role assignments. Grant this identity the necessary roles to access your resources (e.g., Cognitive Services User role on your Azure OpenAI resource). This avoids needing service principal credentials in Application Settings.
Configure Startup Command:
- Go to Settings -> Configuration.
- Select the General settings tab.
- Scroll down to Startup Command.
- Enter the following command:
```
playwright install --with-deps && chainlit run app.py -w --port 8000 --host 0.0.0.0
```
  - playwright install --with-deps: Installs Playwright browsers and their OS dependencies before starting the app.
  - chainlit run app.py: The command to start your application. Replace app.py if your main script has a different name.
  - -w: Enables watchdog for auto-reloading on code changes. Useful during setup, consider removing for stable production.
  - --port 8000: Tells Chainlit to listen on port 8000. Azure App Service routes external traffic (port 80/443) internally to this port.
  - --host 0.0.0.0: Makes Chainlit accessible within the container's network.
- Click Save at the top and Continue to confirm the restart.
Enable Web Sockets:
- Still in Configuration -> General settings.
- Find the Web sockets setting and toggle it to On. Chainlit requires WebSockets for communication.
- Click Save again.

Post-Deployment

Monitor Deployment: Check the Deployment Center for the status of the GitHub Actions workflow. Look for green checkmarks.
Check Logs: If deployment fails or the app doesn't start, go to Monitoring -> Log stream to view real-time logs from the container. Look for errors during dependency installation, Playwright setup, or application startup.
Access Your App: Once deployment is successful and the app is running, navigate to the URL provided on the App Service Overview page (e.g., https://<your-app-name>.azurewebsites.net).
Test Thoroughly: Verify all functionalities, especially those involving:
- Plugins using Playwright (Nutrition, Fitness).
- Email sending via SMTP/Gmail.
- Calendar event generation/sending.
- User profile saving/loading (check the SQLite DB).
- Interactions with Azure OpenAI agents.

Troubleshooting Common Issues

5xx Server Errors: Often indicate a crash during startup. Check the Log stream immediately.
Dependency Errors: Ensure all packages are in requirements.txt with correct versions. Check build logs in Deployment Center or GitHub Actions.
Playwright Errors: Double-check the playwright install --with-deps command in the Startup Command. Ensure it runs before chainlit run. Check Log stream for related errors.
Environment Variable Errors: Verify Application settings names exactly match os.getenv("VAR_NAME") calls in your code. Case sensitivity matters. Check Log stream for None values being used where secrets are expected.
File System Errors (SQLite): Ensure you've updated the database path to /home/data/memory.db in your plugins and that the startup command allows the app to create the /home/data directory if needed (though App Service usually provides /home). Check Log stream for permission errors.
Websocket Errors: Confirm Web sockets are enabled in General Settings. Check browser developer console for connection errors.
Timeout Errors: If your app takes a long time to start, App Service might time out. Ensure startup is reasonably fast. Consider optimizing imports or using a higher App Service Plan tier if needed.

deshneni-akhil/deployment_steps_azure.md

Select an option

No results found