Merge branch 'main' into azdenvgetval

Author: pamelafox

.devcontainer/devcontainer.json

@@ -54,7 +54,7 @@
 		}
 	},
 	// Use 'postCreateCommand' to run commands after the container is created.
-	"postCreateCommand": "pip install -r requirements-dev.txt && pip install -e src",
+	"postCreateCommand": "pip install -r requirements-dev.txt && pip install -e src/backend",
 	// Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
 	"remoteUser": "vscode"
 }

.github/workflows/app-tests.yaml

@@ -5,9 +5,13 @@ on:
     branches: [ main ]
   pull_request:
     branches: [ main ]
+  workflow_dispatch:
+
+permissions:
+  contents: read
 
 jobs:
-  test_package:
+  test-package:
     name: Test ${{ matrix.os }} Python ${{ matrix.python_version }}
     runs-on: ${{ matrix.os }}
     strategy:
@@ -51,12 +55,12 @@ jobs:
             python -m pip install -r requirements-dev.txt
         - name: Install app as editable app
           run: |
-            python -m pip install -e src
+            python -m pip install -e src/backend
         - name: Setup local database with seed data
           run: |
             cp .env.sample .env
-            python ./src/fastapi_app/setup_postgres_database.py
-            python ./src/fastapi_app/setup_postgres_seeddata.py
+            python ./src/backend/fastapi_app/setup_postgres_database.py
+            python ./src/backend/fastapi_app/setup_postgres_seeddata.py
         - name: Setup node
           uses: actions/setup-node@v4
           with:
@@ -65,4 +69,8 @@ jobs:
           run: |
             cd ./src/frontend
             npm install
-            npm run build
+            npm run build
+        - name: Run MyPy
+          run: python3 -m mypy .
+        - name: Run Pytest
+          run: python3 -m pytest

.github/workflows/python-code-quality.yaml

@@ -3,23 +3,34 @@ name: Python code quality
 on:
   push:
     branches: [ main ]
+    paths:
+      - '**.py'
+
   pull_request:
     branches: [ main ]
+    paths:
+      - '**.py'
+
+  workflow_dispatch:
+
+permissions:
+  contents: read
 
 jobs:
-  build:
+  checks-format-and-lint:
     runs-on: ubuntu-latest
     steps:
         - uses: actions/checkout@v4
         - name: Set up Python 3
           uses: actions/setup-python@v5
           with:
             python-version: "3.12"
+            cache: 'pip'
         - name: Install dependencies
           run: |
-            python -m pip install --upgrade pip
-            pip install -r requirements-dev.txt
+            python3 -m pip install --upgrade pip
+            python3 -m pip install ruff
         - name: Lint with ruff
           run: ruff check .
         - name: Check formatting with ruff
-          run: ruff format --check .
+          run: ruff format . --check

README.md

@@ -13,6 +13,7 @@ This project is designed for deployment to Azure using [the Azure Developer CLI]
 * [Local development](#local-development)
 * [Costs](#costs)
 * [Security guidelines](#security-guidelines)
+* [Guidance](#guidance)
 * [Resources](#resources)
 
 ## Features
@@ -58,6 +59,7 @@ A related option is VS Code Dev Containers, which will open the project in your
 1. Make sure the following tools are installed:
 
     * [Azure Developer CLI (azd)](https://aka.ms/install-azd)
+    * [Node.js 18+](https://nodejs.org/download/)
     * [Python 3.10+](https://www.python.org/downloads/)
     * [PostgreSQL 14+](https://www.postgresql.org/download/)
     * [pgvector](https://github.com/pgvector/pgvector)
@@ -99,6 +101,8 @@ Once you've opened the project in [Codespaces](#github-codespaces), [Dev Contain
 
     This will create a folder under `.azure/` in your project to store the configuration for this deployment. You may have multiple azd environments if desired.
 
+3. (Optional) If you would like to customize the deployment to [use existing Azure resources](docs/deploy_existing.md), you can set the values now.
+
 3. Provision the resources and deploy the code:
 
     ```shell
@@ -128,9 +132,9 @@ Since the local app uses OpenAI models, you should first deploy it for the optim
 1. Run these commands to install the web app as a local package (named `fastapi_app`), set up the local database, and seed it with test data:
 
     ```bash
-    python3 -m pip install -e src
-    python ./src/fastapi_app/setup_postgres_database.py
-    python ./src/fastapi_app/setup_postgres_seeddata.py
+    python3 -m pip install -e src/backend
+    python ./src/backend/fastapi_app/setup_postgres_database.py
+    python ./src/backend/fastapi_app/setup_postgres_seeddata.py
     ```
 
 2. Build the frontend:
@@ -139,7 +143,7 @@ Since the local app uses OpenAI models, you should first deploy it for the optim
     cd src/frontend
     npm install
     npm run build
-    cd ../..
+    cd ../../
     ```
 
     There must be an initial build of static assets before running the backend, since the backend serves static files from the `src/static` directory.
@@ -173,12 +177,22 @@ You may try the [Azure pricing calculator](https://azure.microsoft.com/pricing/c
 * Azure PostgreSQL Flexible Server: Burstable Tier with 1 CPU core, 32GB storage. Pricing is hourly. [Pricing](https://azure.microsoft.com/pricing/details/postgresql/flexible-server/)
 * Azure Monitor: Pay-as-you-go tier. Costs based on data ingested. [Pricing](https://azure.microsoft.com/pricing/details/monitor/)
 
-## Security Guidelines
+## Security guidelines
 
 This template uses [Managed Identity](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview) for authenticating to the Azure services used (Azure OpenAI, Azure PostgreSQL Flexible Server).
 
 Additionally, we have added a [GitHub Action](https://github.com/microsoft/security-devops-action) that scans the infrastructure-as-code files and generates a report containing any detected issues. To ensure continued best practices in your own repository, we recommend that anyone creating solutions based on our templates ensure that the [Github secret scanning](https://docs.github.com/code-security/secret-scanning/about-secret-scanning) setting is enabled.
 
+## Guidance
+
+Further documentation is available in the `docs/` folder:
+
+* [Deploying with existing resources](docs/deploy_existing.md)
+* [Monitoring with Azure Monitor](docs/monitoring.md)
+* [Load testing](docs/loadtesting.md)
+
+Please post in the issue tracker with any questions or issues.
+
 ## Resources
 
 * [RAG chat with Azure AI Search + Python](https://github.com/Azure-Samples/azure-search-openai-demo/)

azure.yaml

@@ -4,20 +4,20 @@ metadata:
     template: [email protected]
 services:
     web:
-        project: ./src
+        project: ./src/backend
         language: py
         module: web
         host: containerapp
         hooks:
-            prepackage:
+            prebuild:
                 windows:
                     shell: pwsh
-                    run:  cd frontend;npm install;npm run build
+                    run:  cd ../frontend;npm install;npm run build
                     interactive: false
                     continueOnError: false
                 posix:
                     shell: sh
-                    run:  cd frontend;npm install;npm run build
+                    run:  cd ../frontend;npm install;npm run build
                     interactive: false
                     continueOnError: false
 hooks:

docs/deploy_existing.md

@@ -0,0 +1,18 @@
+# Deploying with existing Azure resources
+
+If you already have existing Azure resources, or if you want to specify the exact name of new Azure Resource, you can do so by setting `azd` environment values.
+You should set these values before running `azd up`. Once you've set them, return to the [deployment steps](../README.md#deployment).
+
+### Openai.com OpenAI account
+
+1. Run `azd env set DEPLOY_AZURE_OPENAI false`
+1. Run `azd env set OPENAI_CHAT_HOST openaicom`
+2. Run `azd env set OPENAI_EMBED_HOST openaicom`
+3. Run `azd env set OPENAICOM_KEY {Your OpenAI API key}`
+4. Run `azd up`
+
+You can retrieve your OpenAI key by checking [your user page](https://platform.openai.com/account/api-keys).
+Learn more about creating an OpenAI free trial at [this link](https://openai.com/pricing).
+Do *not* check your key into source control.
+
+When you run `azd up` after and are prompted to select a value for `openAiResourceGroupLocation`, you can select any location as it will not be used.

docs/images/appinsights_trace.png

@@ -0,0 +1,38 @@
+## Load testing
+
+We recommend running a loadtest for your expected number of users.
+You can use the [locust tool](https://docs.locust.io/) with the `locustfile.py` in this sample
+or set up a loadtest with Azure Load Testing.
+
+To use locust, first install the dev requirements that includes locust:
+
+```shell
+python -m pip install -r requirements-dev.txt
+```
+
+Or manually install locust:
+
+```shell
+python -m pip install locust
+```
+
+Then run the locust command, specifying the name of the User class to use from `locustfile.py` or using the default class. We've provided a `ChatUser` class that simulates a user asking questions and receiving answers.
+
+```shell
+locust
+```
+
+Open the locust UI at [http://localhost:8089/](http://localhost:8089/), the URI displayed in the terminal.
+
+Start a new test with the URI of your website, e.g. `https://my-chat-app.containerapps.io`.
+Do *not* end the URI with a slash. You can start by pointing at your localhost if you're concerned
+more about load on OpenAI than on Azure Container Apps and PostgreSQL Flexible Server.
+
+For the number of users and spawn rate, we recommend starting with 20 users and 1 users/second.
+From there, you can keep increasing the number of users to simulate your expected load.
+
+Here's an example loadtest for 20 users and a spawn rate of 1 per second:
+
+![Screenshot of Locust charts showing 5 requests per second](images/locust_loadtest.png)
+
+After each test, check the local or App Service logs to see if there are any errors.

docs/images/locust_loadtest.png

@@ -0,0 +1,17 @@
+
+# Monitoring with Azure Monitor
+
+By default, deployed apps use Application Insights for the tracing of each request, along with the logging of errors.
+
+To see the performance data, go to the Application Insights resource in your resource group, click on the "Investigate -> Performance" blade and navigate to any HTTP request to see the timing data.
+To inspect the performance of chat requests, use the "Drill into Samples" button to see end-to-end traces of all the API calls made for any chat request:
+
+![Tracing screenshot](images/appinsights_trace.png)
+
+To see any exceptions and server errors, navigate to the "Investigate -> Failures" blade and use the filtering tools to locate a specific exception. You can see Python stack traces on the right-hand side.
+
+You can also see chart summaries on a dashboard by running the following command:
+
+```shell
+azd monitor
+```