Skip to content

setup_instructions_manual

Jump to bottom
Paul Lizer edited this page Sep 30, 2025 · 1 revision

Simple Chat - Manual Setup Instructions

Return to top

Provision Azure Resources

Deploy the necessary Azure services. For a quick estimate of monthly costs based on recommended baseline SKUs for a Demo/Proof-of-Concept (POC)/Minimum Viable Product (MVP) solution, refer to the Azure Pricing Calculator Link. The services and SKUs below are reflected in that estimate.

Important

The following recommended SKUs are intended for Development, Demo, POC, or MVP purposes only. You must scale these services appropriately based on expected user load, data volume, and performance requirements when moving to a Production environment. Factors like concurrent users, document ingestion rate, and query complexity will influence the required tiers and instance counts.

Service Type Recommended Minimum SKU (for Dev/Demo/POC/MVP) Description / Notes
App Service (Frontend) Premium V3 P0v3 (1 Core, 4 GB RAM, 250 GB Storage), Linux Hosts the Python Flask web application. Consider scaling up (P1v3+) or out (multiple instances) for production.
Azure OpenAI (GPT) Standard S0, gpt-4o deployment Powers core chat functionality and optional Metadata Extraction. Choose model based on cost/performance needs. Pay-as-you-go pricing.
Azure OpenAI (Embedding) Standard S0, text-embedding-3-small deployment Required for RAG (Your Workspace, My Groups). Generates vector embeddings. Pay-as-you-go.
Azure OpenAI (Image Gen) Standard S0, dall-e-3 deployment (Optional) Required only if Image Generation feature is enabled. Pay-as-you-go per image.
Azure AI Search Standard S1 (consider S2/S3 for larger scale/HA) Stores and indexes document chunks for RAG. Includes Semantic Ranker capacity. Scale units/replicas/partitions for performance/HA.
Content Safety Standard S0 (Optional) Required only if Content Safety feature is enabled. Pay-as-you-go per 1k text records / 1k images.
Document Intelligence Standard S0 Used for text/layout extraction from various file types during ingestion. Pay-as-you-go per page processed.
Cosmos DB (NoSQL) Autoscale provisioned throughput (Start ~1000 RU/s), Single-Region Write Stores metadata, conversations, settings. Autoscale helps manage costs, but monitor RU consumption and adjust max RU for production loads.
Video Indexer Standard Tier (Optional) Required only if Video Extraction feature is enabled. Pay-as-you-go per input content minute (All Insights).
Speech Service Standard S0 (Optional) Required only if Audio Extraction feature is enabled. Pay-as-you-go per audio hour (Standard fast transcription).
Storage Account General Purpose V2, LRS, Hot Tier (Optional) Required if Enhanced Citations feature is enabled. Stores processed files. Hierarchical Namespace (ADLS Gen2) recommended. - OR - Required if you want to use Azure Storage for temporaty file storage which is recommend for scalability and better performance
Azure Cache for Redis Standard Tier, C0 cache size (Optional) Required only if you need the performance, scalability, and distributed session support provided by Redis Cache.

Note: Pricing is subject to change and varies significantly based on usage, region, specific configurations (e.g., network security, backup policies), and selected tiers. Always use the official Azure Pricing Calculator and monitor your Azure costs closely.

Deployment Steps:

  1. Create or Select a Resource Group:
    • Group all related resources within a single Azure Resource Group (e.g., rg-simple-chat-prod, rg-simple-chat-dev).
    • Deploy resources in the same Azure region where possible to minimize latency, unless specific service availability or compliance dictates otherwise (e.g., Azure OpenAI model availability).
  2. Deploy App Service:
    • Create an Azure App Service instance.
    • Publish: Code
    • Runtime stack: Python 3.12
    • Operating System: Linux
    • Region: Choose your desired region.
    • App Service Plan: Create a new Linux plan using the Premium V3 (P0v3) tier (or higher for production). Zone redundancy typically Disabled for baseline, enable for HA if needed.
    • Review Networking (Public access defaults), Deployment, Monitoring settings. Modify based on organizational security/operational requirements.
    • Note the default App Name and URL (e.g., https://my-simplechat-app.azurewebsites.net). This URL will be needed for AAD App Registration redirects.
  3. Deploy Azure OpenAI Service(s):
    • You can deploy a single Azure OpenAI resource hosting all models or separate resources (e.g., one for GPT, one for Embeddings) based on regional availability or management preference.
    • Create an Azure OpenAI resource. Select Standard S0 pricing tier.
    • Deploy Models: Within the Azure OpenAI Studio for your resource(s), deploy the required models with custom deployment names:
      • GPT Model: e.g., gpt-4o (Required for chat, optional for metadata). Note the Deployment Name.
      • Embedding Model: e.g., text-embedding-3-small (Required for Workspaces/RAG). Note the Deployment Name.
      • Image Generation Model: e.g., dall-e-3 (Required for optional Image Generation). Note the Deployment Name.
    • Review Networking settings (default public access, modify as needed).
    • If using Managed Identity authentication later, you will need to grant the App Service's Managed Identity the Cognitive Services OpenAI User role on this resource(s).
  4. Deploy Azure AI Search:
    • Create an Azure AI Search service.
    • Select the Standard S1 tier (or higher based on scale/HA needs). Consider replicas/partitions for production.
    • Review Networking settings.
    • You will initialize indexes later (Initializing Indexes).
    • If using Managed Identity, grant the App Service's Managed Identity the Search Index Data Contributor role on this resource.
  5. Deploy Azure Cosmos DB:
    • Create an Azure Cosmos DB account.
    • Select the Azure Cosmos DB for NoSQL API.
    • Capacity mode: Provisioned throughput. Choose Autoscale.
    • Set Max throughput at the database level initially (e.g., start with 1000 RU/s, monitor and adjust).
      • Note: Autoscale automatically adjusts the provisioned Request Units (RU/s) between 10% and 100% of this maximum value based on usage (e.g., 1000 max RU/s scales between 100 - 1000 RU/s).
      • Container-Level Scaling (Recommended Post-Setup): While you set an initial database-level throughput, it's highly recommended to configure Autoscale throughput per container after the application creates them (or manually create them with these settings). For optimal performance and cost-efficiency, consider setting the maximum Autoscale throughput for key containers as follows:
        • messages container: 4000 RU/s (will scale between 400 - 4000 RU/s)
        • documents container: 4000 RU/s (will scale between 400 - 4000 RU/s)
        • group_documents container: 4000 RU/s (will scale between 400 - 4000 RU/s)
        • Other containers (like settings, feedback, archived_conversations) often have lower usage and can typically start with a lower maximum (e.g., 1000 RU/s, scaling 100-1000 RU/s), but monitor their consumption.
    • Apply Free Tier Discount: DO NOT APPLY (Free tier throughput is insufficient).
    • Limit total account throughput: Uncheck (DISABLE).
    • Review Networking, Backup Policy, Encryption settings.
    • If using Managed Identity, grant the App Service's Managed Identity the Cosmos DB Built-in Data Contributor role (or create custom roles for least privilege). Note: Managed Identity support for Cosmos DB data plane might require specific configurations. Key-based auth is simpler initially.
  6. Deploy Azure AI Document Intelligence:
    • Create an Azure AI Document Intelligence (formerly Form Recognizer) resource.
    • Select the Standard S0 pricing tier.
    • Review Networking settings.
    • If using Managed Identity, grant the App Service's Managed Identity the Cognitive Services User role on this resource.
  7. Deploy Azure AI Content Safety (Optional):
    • If using the Content Safety feature, create an Azure AI Content Safety resource.
    • Select the Standard S0 pricing tier.
    • Review Networking settings.
    • If using Managed Identity, grant the App Service's Managed Identity the Cognitive Services Contributor role on this resource.
  8. Deploy Azure Video Indexer (Optional):
    • If using the Video Extraction feature, create an Azure Video Indexer resource.
    • You'll need to associate it with an Azure Media Services account (can be created during VI setup) and a Storage Account (used for temporary processing, can be new or existing).
    • Managed Identity (System-assigned) is typically enabled by default.
    • Note the Account ID, Location, and an API Key (Subscription level or Account level). These will be configured in Admin Settings.
  9. Deploy Azure Speech Service (Optional):
    • If using the Audio Extraction feature, create an Azure AI Speech resource.
    • Select the Standard S0 pricing tier.
    • Review Networking and Identity settings.
    • Note the Endpoint, Region/Location, and one of the Keys. These will be configured in Admin Settings.
  10. Deploy Storage Account (Optional):
    • If using the Enhanced Citations feature, create an Azure Storage Account.
    • Performance: Standard.
    • Redundancy: LRS (or higher based on requirements).
    • Account Kind: StorageV2 (general purpose v2).
    • Enable hierarchical namespace (Azure Data Lake Storage Gen2) is recommended for better organization if storing large volumes.
    • Review Networking, Data protection, Encryption settings.
    • Note the Connection String (under Access Keys or SAS token). This will be configured in Admin Settings. If using Managed Identity, grant the App Service's Managed Identity the Storage Blob Data Contributor role.
    • After deployment, note the Connection String (under Access Keys or SAS token). This will be configured in Admin Settings. If using Managed Identity, grant the App Service's Managed Identity the Storage Blob Data Contributor role.
    • Navigate to Data Storage > Containers > + Container. Add two new containers - user-documents and `group-documents
  11. Deploy Azure Cache for Redis (Optional):
    • Create an Azure Cache for Redis service.
    • Name: Choose a unique name for your Redis instance (e.g., simplechat-redis).
    • Region: Select the same region as your App Service for lowest latency.
    • Cache SKU: Standard.
    • Cache Size: C0 (or higher based on requirements).
    • Networking: Set to Public for initial setup (can be made private later for enhanced security).
    • Advanced:
      • Enable Access Keys Authentication (required for key-based access).
      • All other advanced settings can remain at their defaults unless you have specific requirements.
    • After Redis is created, note the Host Name and Access Keys (if using key authentication).
    • If using managed identities, enable Entra Authentication and select the App Service managed identity.
    • The Redis service can take 15-30 minutes to fully deploy.
  12. Use Azure Storage for temporary data data (Optional):
    • Create an Azure Storage Account if you previously created Enhanced Citations you can use it. Otherwise look at step 11 for recommendations on settings.
    • Enable Storage Account Key Access
      • Goto the storage account
      • Click on Configuration (in the Settings section)
      • Click on Enable Key Access and click Save
    • Create a FileShare:
      • Cick on File Shares in the Data Storage section
      • Click Add File Share
      • Give it a name (write it down for use later)
      • Click Next: Backup
      • Turn off enable backup, unless you are using this share for other files
      • Click Review and Create, then Create
    • Create the Share in your App Service:
      • Return to your App Service
      • Click on Configuration (the in Settings Section)
      • Click on Path Mappings
      • Click on Add New Azure Storage Mount
        • Give it a name
        • Use Basic for Configuration Options
        • Select your storage account
        • Select Azure Files for Storage Type
        • Select SMB for Protocal
        • Select the FileShare your created for the Storage Container
        • Set the mount path /sc-temp-files - Important to use this name
        • Click OK and then click Save

Application-Specific Configuration Steps

Return to top

With the Azure resources provisioned, proceed with configuring the application itself. Perform these steps in order.

Setting Up Authentication (Azure AD / Entra ID)

The application uses Azure Active Directory (Entra ID) for user authentication and role management.

  1. Register an Application in Azure AD:

    • Navigate to Azure Active Directory > App registrations > + New registration.
    • Give it a name (e.g., SimpleChatApp-Prod).
    • Select Accounts in this organizational directory only (or adjust if multi-tenant access is needed).
    • Set the Redirect URI:
      • Select Web platform.
      • Enter the URI: https://<your-app-service-name>.azurewebsites.net/.auth/login/aad/callback (Replace <your-app-service-name> with your actual App Service name).
    • Click Register.
    • Note the Application (client) ID and Directory (tenant) ID. These are needed for the .env file (CLIENT_ID, TENANT_ID).
    • Next, click the Authentication link in the Manage section
    • In the Web Redirect URIs section of the page click Add URI
    • Enter the URI: https://<your-app-service-name>.azurewebsites.net/getAToken (Replace <your-app-service-name> with your actual App Service name).
    • Next in the Front-channel logout URL section of the page
    • Enter the URI: https://<your-app-service-name>.azurewebsites.net/logout (Replace <your-app-service-name> with your actual App Service name).
    • Now look at the Implicit grant and hybrid flows section
    • Make sure the checked for *ID tokens (used for implicit and hybrid flows) is checked
    • Click the Save button App Registration Settings (Note: Image shows general area, details might differ slightly)
    • Click on the Certificates and secrets link in the manage section
    • Click on Client Secrets
    • Verify that there is a Secret Named MICROSOFT_PROVIDER_AUTHENTICATION_SECRET
    • If there is not, click on New Client Secret to create a new secret using MICROSOFT_PROVIDER_AUTHENTICATION_SECRET as the name.
    • Make sure you copy the Value before you leave this page. App Registration Settings (Note: Image shows general area, details might differ slightly)

  2. Configure App Service Authentication:

    • Go to your App Service in the Azure portal.
    • Navigate to Settings > Authentication.
    • Click Add identity provider.
    • Identity provider: Microsoft
    • App registration type: Pick an existing app registration in this directory.
    • Select the App registration you just created.
    • Restrict access: Require authentication.
    • Unauthenticated requests: HTTP 302 Found redirect: recommended for web apps.
    • Click Add. This configures the built-in App Service Authentication (Easy Auth).
    • ⚠️ Important ⚠️: After adding the provider, go back into the Authentication settings for the App Service, click Edit on the Microsoft provider.
      • Ensure the Issuer URL is correct (usually https://login.microsoftonline.com/<your-tenant-id>/v2.0 or https://sts.windows.net/<your-tenant-id>/v2.0).
      • Note the Client Secret Setting Name value shown here. This secret (MICROSOFT_PROVIDER_AUTHENTICATION_SECRET) is often automatically added to App Service Application Settings. If the name is not there (or a different name is there) click on Click to edit secret value
      • Click on Add, for the name use MICROSOFT_PROVIDER_AUTHENTICATION_SECRET for the value enter the Key that you copied in the previous step
      • Click Apply, the click Apply again
      • Return to the Edit identity provider page and now select MICROSOFT_PROVIDER_AUTHENTICATION_SECRET for the Client Secret setting name. (It may take a minute for that name to appear)

    App Registration - Authentication Configuration in App Service (Note: Image shows general area, details might differ slightly)

  3. Configure API Permissions:

    • Go back to your App Registration in Azure AD.
    • Navigate to API permissions.
    • Click + Add a permission.
    • Select Microsoft Graph.
    • Select Delegated permissions.
    • Add the following permissions:
      • email
      • offline_access
      • openid
      • profile
      • User.Read (Allows sign-in and reading the user's profile)
      • User.ReadBasic.All (Allows reading basic profiles of all users - often needed for people pickers if not using People.Read.All)
      • (Conditional) People.Read.All: Required if you enable the My Groups feature, as it's used to search for users within your tenant to add to groups. Add this permission if needed.
      • (Conditional) Group.Read.All: Required if you enable the My Groups feature or need to read group memberships and group details for group workspaces. This permission allows the app to list groups and read group properties and memberships in your organization. Add this permission if group-based collaboration or group document access is needed.
    • After adding permissions, click Grant admin consent for [Your Tenant Name]. This is crucial, especially for *.All permissions.

    App Registration - API Permissions

  4. Configure App Roles:

    • In your App Registration, navigate to App roles.
    • Click + Create app role.
    • Create roles based on the following table. Repeat for each role:
    Display Name Allowed member types Value Description Do you want to enable this app role?
    Admins Users/Groups Admin Allows access to Admin Settings page. Yes
    Users Users/Groups User Standard user access to chat features. Yes
    Create Group Users/Groups CreateGroups Allows user to create new groups (if enabled). Yes
    Safety Violation Admin Users/Groups SafetyViolationAdmin Allows access to view content safety violations. Yes
    Feedback Admin Users/Groups FeedbackAdmin Allows access to view user feedback admin page. Yes

    App Registration - App Roles

  5. Assign Users/Groups to Roles via Enterprise Application:

    • App Roles are assigned through the Enterprise Application associated with your App Registration.
    • Navigate to Azure Active Directory > Enterprise applications.
    • Find the application with the same name as your App Registration (or search by Application ID).
    • Select your Enterprise Application.
    • Go to Users and groups.
    • Click + Add user/group.
    • Select the users or security groups you want to grant access.
    • Under Select a role, choose the appropriate App Role (Admins, Users, etc.) you defined.
    • Click Assign. Only assigned users/groups will be able to log in (if "Assignment required?" is enabled on the Enterprise App, which is recommended).

Grant App Registration Access to Azure OpenAI (for Model Fetching)

The application needs permission to list the available models deployed in your Azure OpenAI resource(s). This uses the App Registration's Service Principal.

  1. Go to each Azure OpenAI service resource in the Azure portal.
  2. Select Access control (IAM).
  3. Click + Add > Add role assignment.
  4. Search for and select the role Cognitive Services OpenAI User. Click Next.
  5. Assign access to: Select User, group, or service principal.
  6. Members: Click + Select members.
  7. Search for the name of your App Registration (e.g., SimpleChatApp-Prod). Select it.
  8. Click Select, then Next.
  9. Click Review + assign.
  10. Repeat for all Azure OpenAI resources used by the application (GPT, Embedding, Image Gen if separate).

Add role assignment - Job function role selected Add role assignment - Selecting the Service Principal (App Registration)

Clone the Repository

Get the application code onto your local machine.

  1. Open a terminal or command prompt.
  2. Use Git to clone the repository: 
    git clone <repository-url>
cd <repository-folder>
    (Replace <repository-url> and <repository-folder> accordingly). Alternatively, use GitHub Desktop or download the ZIP and extract it.

Clone the repo options in GitHub UI

Configure Environment Variables (.env File)

Core configuration values are managed via environment variables, typically set in the Azure App Service Application Settings. A .env file is used locally and can be uploaded to populate these settings.

  1. Create .env from Example:

    • Find the example.env file in the cloned repository.
    • Rename or copy it to .env.

  2. Edit .env:

    • Open the .env file in a text editor (like VS Code).
    • Fill in the placeholder values with your actual service details:
    # Azure Cosmos DB
# Use connection string OR endpoint/key OR managed identity
# e.g., https://mycosmosdb.documents.azure.com:443/
AZURE_COSMOS_ENDPOINT="<your-cosmosdb-account-uri>"
AZURE_COSMOS_KEY="<your-cosmosdb-primary-key>"
# Options: "key", "connection_string", "managed_identity"
AZURE_COSMOS_AUTHENTICATION_TYPE="key"

# Azure AD Authentication (Required)
CLIENT_ID="<your-app-registration-client-id>"
TENANT_ID="<your-azure-ad-tenant-id>"
# SECRET_KEY should be a long, random, secret string (e.g., 32+ chars) used for Flask session signing. Generate one securely.
SECRET_KEY="Generate-A-Strong-Random-Secret-Key-Here!"
# AZURE_ENVIRONMENT: Set based on your cloud environment
# Options: "public", "usgovernment", "custom"
AZURE_ENVIRONMENT="public"

  3. Upload Settings to Azure App Service (Recommended using VS Code):

    • Ensure the .env file is saved and closed.
    • In VS Code, with the Azure App Service extension installed and signed in:
      • Option 1 (Command Palette): Press Ctrl+Shift+P (or Cmd+Shift+P), type Azure App Service: Upload Local Settings, select your subscription and App Service instance, then choose the .env file.
      • Option 2 (File Explorer): Right-click the .env file in the VS Code explorer, select Azure App Service: Upload Local Settings, and follow the prompts.
    • This action reads your .env file and sets the corresponding Application Settings in the Azure App Service configuration blade.

    Upload local settings - Option 1 (Command Palette) Upload local settings - Option 2 (Right-click)

  4. (Optional) Download Settings from Azure App Service:

    • To verify or synchronize settings from Azure back to a local .env file:
    • Press Ctrl+Shift+P, type Azure App Service: Download Remote Settings, select your App Service, and choose where to save the file (e.g., overwrite your local .env). This is useful to capture settings automatically added by Azure (like APPLICATIONINSIGHTS_CONNECTION_STRING or WEBSITE_AUTH_AAD_ALLOWED_TENANTS).

    Download remote settings command

  5. First-Time Configuration Wizard:

    • When you first access the admin settings page, a configuration wizard will guide you through the required and optional settings.
    • The wizard will help you configure:
      • Application basics: Title and logo customization
      • GPT API settings: Configure Azure OpenAI endpoints and models
      • Workspace settings: Enable personal and group workspaces
      • Additional services: Configure embedding, AI Search, Document Intelligence, and other required services
      • Optional features: Content safety, user feedback, conversation archiving, and other optional features
    • Required settings are clearly marked, ensuring that you configure all necessary components for your deployment scenario.

Alternate Method: Update App Settings via JSON (Advanced)

You can directly edit Application Settings in the Azure portal using the "Advanced edit" feature, pasting a JSON array. This is useful for bulk updates but requires care not to overwrite essential settings added by Azure.

  1. Navigate to your App Service > Settings > Configuration > Application settings.
  2. Backup Existing Values: Before pasting, copy the current values for critical settings like MICROSOFT_PROVIDER_AUTHENTICATION_SECRET, APPLICATIONINSIGHTS_CONNECTION_STRING, and WEBSITE_AUTH_AAD_ALLOWED_TENANTS.
  3. Prepare JSON: Create a JSON array similar to the example below, inserting your specific values and the backed-up Azure-managed values.
  4. Click Advanced edit.
  5. Carefully replace the existing JSON content with your prepared JSON.
  6. Click OK, then Save.

Example JSON Structure:

[
    // --- Azure Managed / Essential Settings ---
    { "name": "APPLICATIONINSIGHTS_CONNECTION_STRING", "value": "<your-appinsights-connection-string>", "slotSetting": false },
    { "name": "APPINSIGHTS_INSTRUMENTATIONKEY", "value": "<your-appinsights-instrumentation-key>", "slotSetting": false }, // Often same key as connection string contains
    { "name": "MICROSOFT_PROVIDER_AUTHENTICATION_SECRET", "value": "<app-service-auth-secret>", "slotSetting": true }, // CRITICAL - Get from portal if unsure
    { "name": "WEBSITE_AUTH_AAD_ALLOWED_TENANTS", "value": "<your-tenant-id>", "slotSetting": false }, // Usually set by Auth config
    { "name": "WEBSITE_AUTH_ENABLED", "value": "True", "slotSetting": true }, // Should be set by Auth config
    { "name": "WEBSITE_AUTH_DEFAULT_PROVIDER", "value": "AzureActiveDirectory", "slotSetting": true }, // Should be set by Auth config

    // --- Your Application Settings (from .env) ---
    { "name": "AZURE_COSMOS_ENDPOINT", "value": "<your-cosmosdb-endpoint>", "slotSetting": false },
    { "name": "AZURE_COSMOS_KEY", "value": "<your-cosmosdb-key>", "slotSetting": false },
    { "name": "AZURE_COSMOS_DATABASE", "value": "SimpleChat", "slotSetting": false },
    { "name": "AZURE_COSMOS_AUTHENTICATION_TYPE", "value": "key", "slotSetting": false }, // or "managed_identity"
    { "name": "CLIENT_ID", "value": "<your-app-registration-client-id>", "slotSetting": false },
    { "name": "TENANT_ID", "value": "<your-azure-ad-tenant-id>", "slotSetting": false },
    { "name": "SECRET_KEY", "value": "<your-flask-secret-key>", "slotSetting": false },
    { "name": "AZURE_ENVIRONMENT", "value": "public", "slotSetting": false }, // or "usgovernment", or "custom"

    // --- Build & Runtime Settings ---
    { "name": "SCM_DO_BUILD_DURING_DEPLOYMENT", "value": "true", "slotSetting": false }, // Ensures requirements.txt is processed
    { "name": "WEBSITE_HTTPLOGGING_RETENTION_DAYS", "value": "7", "slotSetting": false },

    // --- Optional App Insights Advanced Settings (Defaults usually fine) ---
    { "name": "ApplicationInsightsAgent_EXTENSION_VERSION", "value": "~3", "slotSetting": false },
    { "name": "APPLICATIONINSIGHTSAGENT_EXTENSION_ENABLED", "value": "true", "slotSetting": false },
    { "name": "XDT_MicrosoftApplicationInsights_Mode", "value": "default", "slotSetting": false },
    { "name": "APPINSIGHTS_PROFILERFEATURE_VERSION", "value": "1.0.0", "slotSetting": false },
    { "name": "APPINSIGHTS_SNAPSHOTFEATURE_VERSION", "value": "1.0.0", "slotSetting": false },
    { "name": "SnapshotDebugger_EXTENSION_VERSION", "value": "disabled", "slotSetting": false },
    { "name": "InstrumentationEngine_EXTENSION_VERSION", "value": "disabled", "slotSetting": false },
    { "name": "XDT_MicrosoftApplicationInsights_BaseExtensions", "value": "disabled", "slotSetting": false },
    { "name": "XDT_MicrosoftApplicationInsights_PreemptSdk", "value": "disabled", "slotSetting": false }
]

Warning

Editing Application Settings via JSON is powerful but risky. Incorrectly modifying or omitting settings managed by Azure (especially Authentication or App Insights integration) can break functionality. Proceed with caution and always back up existing values. Using the .env upload method is generally safer.

alt text

Initializing Indexes in Azure AI Search

The application requires two Azure AI Search indexes: one for personal user documents and one for shared group documents. The schemas are defined in JSON files within the repository.

  1. Locate Index Schema Files:

    • In your cloned repository, find the artifacts/ai_search_index/ directory.
    • It contains ai_search-index-user.json and ai_search-index-group.json.
    📁 SimpleChat
     └── 📁 artifacts
         └── 📁 ai_search_index
             ├── ai_search-index-group.json
             └── ai_search-index-user.json

  2. Access Azure AI Search in Azure Portal:

    • Navigate to your Azure AI Search service resource.
    • Under Search management, select Indexes.

  3. Create Indexes from JSON:

    • Click + Add index.
    • Change the creation method from Enter index name to Import from JSON.
    • User Index:
      • Open ai_search-index-user.json locally, copy its entire content.
      • Paste the JSON into the Index definition (JSON) editor in the portal.
      • The Index Name should automatically populate as simplechat-user-index.
      • Click Save.
    • Group Index:
      • Click + Add index again and choose Import from JSON.
      • Open ai_search-index-group.json locally, copy its content.
      • Paste the JSON into the editor.
      • The Index Name should populate as simplechat-group-index.
      • Click Save.

  4. Verify Indexes:

    • You should now see simplechat-user-index and simplechat-group-index listed under Indexes.

Note

Automatic Schema Update Feature: If you happen to miss this step or deploy an updated version of the application with new required index fields, the application includes a mechanism to help. When an Admin user navigates to the Admin > App Settings page, the application backend checks the schemas of the existing simplechat-user-index and simplechat-group-index against the expected schema. If missing fields are detected, notification buttons will appear at the top of the Admin Settings page: "Add missing user fields" and "Add missing group fields". Clicking these buttons will automatically add the missing fields to your Azure AI Search indexes without data loss. While this feature provides resilience, it's still recommended to create the indexes correctly using the JSON definitions initially.

alt text

Installing and Deploying the Application Code

Deploy the application code from your local repository to the Azure App Service.

Deploying via VS Code (Recommended for Simplicity)

  1. Ensure Azure Extensions are Installed: You need the Azure Tools Extension Pack and the Azure App Service extension in VS Code.
  2. Sign In to Azure: Use the Azure extension to sign in to your Azure account.
  3. Deploy:
    • In the VS Code Activity Bar, click the Azure icon.
    • Expand App Service, find your subscription and the App Service instance you created.
    • Right-click on the App Service name.
    • Select Deploy to Web App....
    • Browse and select the folder containing the application code (the root folder you cloned, e.g., SimpleChat).
    • VS Code will prompt to confirm the deployment, potentially warning about overwriting existing content. Click Deploy.
    • Make sure your requirements.txt file is up-to-date before deploying. The deployment process (SCM_DO_BUILD_DURING_DEPLOYMENT=true) will use this file to install dependencies on the App Service.
    • Monitor the deployment progress in the VS Code Output window.

Deploying via Azure CLI (Zip Deploy)

This method involves creating a zip file of the application code and uploading it using the Azure CLI. Refer to the official documentation for detailed steps: Quickstart: Deploy a Python web app to Azure App Service.

Key Steps:

  1. Create the ZIP file:

    • Navigate into the application's root directory (e.g., SimpleChat) in your terminal.
    • Create a zip file containing only the necessary application files and folders. Crucially, zip the contents, not the parent folder itself.
    • Include:
      • static/ folder
      • templates/ folder
      • requirements.txt file
      • All Python files (*.py) at the root level (e.g., app.py, utils.py, etc.).
      • Any other necessary support files or directories at the root level.
    • Exclude:
      • .git/ folder and .gitignore
      • .vscode/ folder
      • pycache/ directories
      • .env, example.env (environment variables are set in App Settings)
      • .deployment, Dockerfile, .dockerignore (unless specifically using Docker deployment)
      • README.md, LICENSE, .DS_Store, etc.
      • Any local virtual environment folders (e.g., .venv, env).

    alt text

    alt text

    Ensure SCM_DO_BUILD_DURING_DEPLOYMENT is Set: Verify this application setting is true in your App Service configuration to ensure dependencies are installed from requirements.txt during deployment.

  2. Deploy using Azure CLI:

    az login # Sign in if you haven't already
az account set --subscription "<Your-Subscription-ID>"

az webapp deploy --resource-group <Your-Resource-Group-Name> --name <Your-App-Service-Name> --src-path ../deployment.zip --type zip

Running the Application

  1. Navigate to your App Service in the Azure Portal.
  2. On the Overview blade, find the Default domain URL (e.g., https://my-simplechat-app.azurewebsites.net).
  3. Click the URL to open the application in your browser.
  4. You should be redirected to the Microsoft login page to authenticate via Azure AD. Log in with a user account that has been assigned a role in the Enterprise Application.

alt text

Upgrading the Application

Return to top

Keeping your Simple Chat application up-to-date involves deploying the newer version of the code. Using Deployment Slots is the recommended approach for production environments to ensure zero downtime and provide easy rollback capabilities.

alt text

Using Deployment Slots (Recommended for Production/Staging)

  1. Create a Deployment Slot:

    • In your App Service, go to Deployment > Deployment slots.
    • Click + Add Slot. Give it a name (e.g., staging).
    • Choose to clone settings from the production slot initially.
    • This creates a fully functional, independent instance of your app connected to the same App Service Plan.

  2. Deploy New Version to Staging Slot:

    • Deploy the updated application code (using VS Code deployment or az webapp deploy) specifically targeting the staging slot.

    • VS Code: When deploying, VS Code will prompt you to select the target slot (production or staging). Choose staging.

    • Azure CLI: Add the --slot staging parameter to your az webapp deploy command:

      az webapp deploy --resource-group <RG_Name> --name <App_Name> --src-path <Zip_Path> --type zip --slot staging

  3. Test the Staging Slot:

    • The staging slot has its own unique URL (e.g., https://my-simplechat-app-staging.azurewebsites.net). Access this URL directly.
    • Thoroughly test all application functionality, including new features and critical paths, in the staging environment. This slot typically uses the same backend resources (Cosmos DB, AI Search, etc.) as production unless configured otherwise (e.g., using slot-specific Application Settings).

  4. Swap Staging to Production:

    • Once confident the new version in staging is stable, go back to Deployment slots in the Azure portal.

    • Click the Swap button.

    • Configure the swap:

      • Source: staging
      • Target: production

    • Azure performs a "warm-up" of the staging slot instance before redirecting production traffic to it. The previous production code is simultaneously moved to the staging slot. This swap happens near-instantly from a user perspective.

    • Azure CLI Swap Command:

      az webapp deployment slot swap --resource-group <RG_Name> --name <App_Name> --slot staging --target-slot production

  5. Monitor and Rollback (If Necessary):

    • Monitor the application closely after the swap using Application Insights and user feedback.
    • If critical issues arise, you can perform another Swap operation, this time swapping production (which now contains the problematic code) back with staging (which now contains the previous stable code). This provides an immediate rollback.

Using Direct Deployment to Production (Simpler, for Dev/Test or Low Impact Changes)

You can deploy directly to the production slot using the same VS Code or Azure CLI methods described in the initial deployment section, simply omitting the --slot parameter or choosing the production slot in VS Code.

Warning

Deploying directly to production overwrites the live code. This will cause a brief application restart and offers no immediate rollback capability (you would need to redeploy the previous version). This method is generally not recommended for production environments or significant updates due to the downtime and risk involved.

Automate via CI/CD

For mature development practices, set up a Continuous Integration/Continuous Deployment (CI/CD) pipeline using tools like GitHub Actions or Azure DevOps Pipelines. A typical pipeline would:

  1. Trigger on code commits/merges to specific branches (e.g., main, release/*).
  2. Build the application artifact (e.g., create the zip file).
  3. Deploy the artifact to the staging slot.
  4. (Optional) Run automated tests against the staging slot.
  5. Require manual approval (or automatically trigger based on test results) to perform the swap operation to production.
Clone this wiki locally