fixed documentation order and links closes #446 closes #482 closes #451

README.md

@@ -1,42 +1,46 @@
 # What's new - January 2025
+
 A new year brings some much requested feature updates to one of our most popular AI chat repos!
-- **[Managed Identity-based security](/docs/10-managed-identities.md)**. This uses Azure's underlying RBAC and removes (almost) all keys/secrets.
-- `appreg_setup.ps1` helper script to **[create the App Registration for you](/docs/5-add-identity.md#azure-ad-authentication-provider)** in Entra (if you have the permissions). Less copypasta means happier devs 🥰 
+
+- **[Managed Identity-based security](/docs/9-managed-identities.md)**. This uses Azure's underlying RBAC and removes (almost) all keys/secrets.
+- `appreg_setup.ps1` helper script to **[create the App Registration for you](/docs/3-add-identity.md#entra-id-authentication-provider)** in Entra ID (if you have the permissions). Less copypasta means happier devs 🥰
 
 # Unleash the Power of Azure OpenAI
 
 1. [Introduction](#introduction)
-1. [Solution Overview](/docs/1-introduction.md)
-1. [Deploy to Azure](#deploy-to-azure)
-1. [Run from your local machine](/docs/3-run-locally.md)
-1. [Deploy to Azure with GitHub Actions](/docs/4-deploy-to-azure.md)
-1. [Add identity provider](/docs/5-add-identity.md)
-1. [Chatting with your file](/docs/6-chat-over-file.md)
-1. [Persona](/docs/6-persona.md)
-1. [Extensions](/docs/8-extensions.md)
-1. [Environment variables](/docs/9-environment-variables.md)
-1. [Managed Identity-based deployment](/docs/10-managed-identities.md)
-1. [Migration considerations](/docs/migration.md)
+2. [Solution Overview](./docs/1-introduction.md)
+3. [Run from your local machine](./docs/2-run-locally.md)
+4. [Add identity provider](./docs/3-add-identity.md)
+5. [Deploy to Azure](#deploy-to-azure)
+6. [Deploy to Azure with GitHub Actions](./docs/4-deploy-to-azure.md)
+7. [Chatting with your file](./docs/5-chat-over-file.md)
+8. [Persona](./docs/6-persona.md)
+9. [Extensions](./docs/7-extensions.md)
+10. [Environment variables](./docs/8-environment-variables.md)
+11. [Managed Identity-based deployment](./docs/9-managed-identities.md)
+12. [Migration considerations](./docs/migration.md)
 
 # Introduction
 
 _Azure Chat Solution Accelerator powered by Azure OpenAI Service_
 
-![](/docs/images/intro.png)
+![Intro Image](/docs/images/intro.png)
 
 _Azure Chat Solution Accelerator powered by Azure OpenAI Service_ is a solution accelerator that allows organisations to deploy a private chat tenant in their Azure Subscription, with a familiar user experience and the added capabilities of chatting over your data and files.
 
 Benefits are:
 
-1. Private: Deployed in your Azure tenancy, allowing you to isolate it to your Azure tenant.
+1. **Private:** Deployed in your Azure tenancy, allowing you to isolate it to your Azure tenant.
 
-2. Controlled: Network traffic can be fully isolated to your network and other enterprise grade authentication security features are built in.
+2. **Controlled:** Network traffic can be fully isolated to your network and other enterprise grade authentication security features are built in.
 
-3. Value: Deliver added business value with your own internal data sources (plug and play) or integrate with your internal services (e.g., ServiceNow, etc).
+3. **Value:** Deliver added business value with your own internal data sources (plug and play) or integrate with your internal services (e.g., ServiceNow, etc).
 
 # Deploy to Azure
 
-You can provision Azure resources for the solution accelerator using either the Azure Developer CLI or the Deploy to Azure button below. Regardless of the method you chose you will still need set up an [identity provider and specify an admin user](/docs/5-add-identity.md)
+You can provision Azure resources for the solution accelerator using either the Azure Developer CLI or the Deploy to Azure button below. Regardless of the method you chose you will still need set up an [identity provider and specify an admin user](/docs/3-add-identity.md).
+
+We recommend you also read the dedicated [Deploy to Azure](./docs/4-deploy-to-azure.md) documentation to understand how to deploy the application using GitHub Actions.
 
 ## Deployment Options
 
@@ -72,9 +76,9 @@ Click on the Deploy to Azure button to deploy the Azure resources for the applic
 [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://aka.ms/anzappazurechatgpt)
 
 > [!IMPORTANT]
-> The application is protected by an identity provider and follow the steps in [Add an identity provider](/docs/5-add-identity.md) section for adding authentication to your app.
+> The application is protected by an identity provider, follow the steps in [Add an identity provider](/docs/3-add-identity.md) section for adding authentication to your app.
 
-[Next](./docs/1-introduction.md)
+[Next: Introduction](./docs/1-introduction.md)
 
 # Contributing
 

azure.yaml

@@ -12,9 +12,9 @@ hooks:
   postdeploy:
     posix:
       shell: sh
-      run: echo -e "\n\033[0;36mTo complete the application setup you will need to configure an identity provider\033[0m\n(see the "Production App Setup" documentation at https://github.com/microsoft/azurechat/blob/main/docs/5-add-identity.md)\n"
+      run: echo -e "\n\033[0;36mTo complete the application setup you will need to configure an identity provider\033[0m\n(see the "Production App Setup" documentation at https://github.com/microsoft/azurechat/blob/main/docs/3-add-identity.md)\n"
       interactive: true
       continueOnError: false
     windows:
       shell: pwsh
-      run: Write-Host "`nTo complete the application setup you will need to configure an identity provider`n(see the 'Production App Setup' documentation at https://github.com/microsoft/azurechat/blob/main/docs/5-add-identity.md)`n" -ForegroundColor Cyan
+      run: Write-Host "`nTo complete the application setup you will need to configure an identity provider`n(see the 'Production App Setup' documentation at https://github.com/microsoft/azurechat/blob/main/docs/3-add-identity.md)`n" -ForegroundColor Cyan

docs/1-introduction.md

@@ -2,8 +2,8 @@
 
 Please make sure the following prerequisites are in place prior to deploying this accelerator:
 
-1. Setup GitHub or Azure AD for Authentication:
-   The [add an identity provider](./5-add-identity.md) section below shows how to configure authentication providers.
+1. Setup GitHub or Entra ID for authentication:
+   The [add an identity provider](./3-add-identity.md) section below shows how to configure authentication providers.
 
 > [!NOTE]
 > You can configure the authentication provider to your identity solution using [NextAuth providers](https://next-auth.js.org/providers/)
@@ -12,19 +12,19 @@ Please make sure the following prerequisites are in place prior to deploying thi
 
 _Azure Chat Solution Accelerator powered by Azure OpenAI Service_ is built using the following technologies:
 
-- [Node.js 18](https://nodejs.org/en): an open-source, cross-platform JavaScript runtime environment.
+- [Node.js 22](https://nodejs.org/en): an open-source, cross-platform JavaScript runtime environment.
 
-- [Next.js 13](https://nextjs.org/docs): enables you to create full-stack web applications by extending the latest React features
+- [Next.js 14](https://nextjs.org/docs): enables you to create full-stack web applications by extending the latest React features.
 
-- [NextAuth.js](https://next-auth.js.org/): configurable authentication framework for Next.js 13
+- [NextAuth.js](https://next-auth.js.org/): configurable authentication framework for Next.js.
 
-- [OpenAI SDK](https://github.com/openai/openai-node) NodeJS library that simplifies building conversational UI
+- [OpenAI SDK](https://github.com/openai/openai-node) NodeJS library that simplifies building conversational UI.
 
-- [Tailwind CSS](https://tailwindcss.com/): is a utility-first CSS framework that provides a series of predefined classes that can be used to style each element by mixing and matching
+- [Tailwind CSS](https://tailwindcss.com/): is a utility-first CSS framework that provides a series of predefined classes that can be used to style each element by mixing and matching.
 
 - [shadcn/ui](https://ui.shadcn.com/): re-usable components built using Radix UI and Tailwind CSS.
 
-- [Azure Cosmos DB](https://learn.microsoft.com/en-GB/azure/cosmos-db/nosql/): fully managed platform-as-a-service (PaaS) NoSQL database to store chat history
+- [Azure Cosmos DB](https://learn.microsoft.com/en-GB/azure/cosmos-db/nosql/): fully managed platform-as-a-service (PaaS) NoSQL database to store chat history.
 
 - [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/overview): Azure OpenAI Service provides REST API access to OpenAI's powerful language models including the GPT-4, GPT-35-Turbo, and Embeddings model series.
 
@@ -46,7 +46,7 @@ The following Azure services can be deployed to expand the feature set of your s
 
 The following high-level diagram depicts the architecture of the solution accelerator:
 
-![Architecture diagram](/docs/images/architecture.png)
+![Architecture diagram](./images/architecture.png)
 
 # Azure Deployment Costs
 
@@ -65,4 +65,6 @@ To reduce costs, you can switch to free SKUs for Azure App Service, Azure AI Sea
 > [!WARNING]
 > To avoid unnecessary costs, remember to destroy your provisioned resources by deleting the resource group.
 
-[Next](./3-run-locally.md)
+## Continue to the next step...
+
+👉 [Next: Run Azure Chat Locally (development)](./2-run-locally.md)

docs/3-run-locally.md → docs/2-run-locally.md

@@ -4,11 +4,11 @@ Clone this repository locally or fork to your GitHub account. Run all of the the
 
 ## Prerequisites
 
-- **History Database**: If you didn't [provision the Azure resources](./4-deploy-to-azure.md), you **must** at least deploy an instance of Azure Cosmos DB in your Azure Subscription to store chat history.
+- **History Database**: If you don't want to [provision the Azure resources](./4-deploy-to-azure.md), you **must** at least deploy an instance of Azure Cosmos DB in your Azure Subscription to store chat history.
 
-- **Identity Provider**: For local development, you have the option of using a username / password to sign in. If you prefer to use an Identity Provider, follow the [instructions](./5-add-identity.md) to add one.
+- **Identity Provider**: For local development, you have the option of using a username / password to sign in. If you prefer to use an Identity Provider, follow the [instructions](./3-add-identity.md) in the next chapter to add one.
 
-## Steps
+## Steps to Run Locally
 
 1. Change directory to the `src` folder
 2. Rename/copy the file `.env.example` to `.env.local` and populate the environment variables based on the deployed resources in Azure.
@@ -18,7 +18,9 @@ Clone this repository locally or fork to your GitHub account. Run all of the the
 
 You should now be prompted to log in with your chosen authentication method (per the pre-requisite configuration).
 
-> **NOTE**  
+> **NOTE**
 > If using Basic Auth (DEV ONLY), any username you enter will create a new user id (hash of username@localhost). You can use this to simulate multiple users. Once successfully logged in, you can start creating new conversations.
 
-[Next](/docs/4-deploy-to-azure.md)
+## Continue to the next step...
+
+👉 [Next: Add an Identity Provider](./3-add-identity.md)

docs/5-add-identity.md → docs/3-add-identity.md

@@ -1,14 +1,14 @@
 # 🪪 Add an Identity Provider
 
-Once the deployment is complete, you will need to add an identity provider to authenticate your app. You will also need to configure an admin user.
+You will need to add an identity provider to authenticate your app. For local development you have the additional option of using a username / password to sign in (less secure). To view reports and admin info throughout Azure Chat, you will also need to specify an admin user by their email address.
 
 > [!NOTE]
 > Only one of the identity providers is required to be configured below.
 
 > [!IMPORTANT]
 > We **strongly** recommend that you store client secrets in Azure Key Vault and reference the Azure Key Vault secrets in your App config settings. If you have created your environment using the templates in this repo, you will already have an Azure Key Vault service deployed which can be used to store a range of other secrets. Details on how to configure Azure App Service settings to use Azure Key Vault references are [here](https://learn.microsoft.com/en-us/azure/app-service/app-service-key-vault-references?tabs=azure-cli#source-app-settings-from-key-vault). Note that you will also need to give yourself appropriate permissions to create secrets in the Key Vault.
 
-Azure Chat uses [NextAuth.js](https://next-auth.js.org) for authentication. NextAuth supports a wide range of identity providers. In this guide, you will learn how to configure GitHub and/or Microsoft Entra ID as identity providers, but many others are also supported. Please refer to the [NextAuth provider documentation](https://next-auth.js.org/providers) for more options.
+Azure Chat uses [NextAuth.js](https://next-auth.js.org) for authentication. NextAuth supports a wide range of identity providers. In this guide, you will learn how to configure GitHub and/or Microsoft Entra ID as identity providers, but many others are also supported.
 
 ## GitHub Authentication Provider
 
@@ -89,23 +89,37 @@ You can use the helper script to create an Azure App Registration and populate t
 > [!NOTE]
 > After completing app setup, ensure your environment variables locally and on Azure App Service are up to date.
 
-```bash
-# Azure AD OAuth app configuration
+> [!IMPORTANT]
+> Please beware that while Microsoft has [renamed](https://learn.microsoft.com/en-us/entra/fundamentals/new-name) Azure AD to Microsoft Entra ID, the environment variables still use the old naming convention. We will update this in the future.
+
+Set environment variables:
 
+```bash
+# Entra ID OAuth App Configuration
 AZURE_AD_CLIENT_ID=
 AZURE_AD_CLIENT_SECRET=
 AZURE_AD_TENANT_ID=
 ```
 
+## Other Identity Providers
+
+Please refer to the [NextAuth provider documentation](https://next-auth.js.org/providers) for more options.
+
+The identity provider can be appended to the `providers` array in the [auth-api.ts](src/features/auth-page/auth-api.ts) file and respective client id and secret added to the environment variables: `.env.local` and Azure App Service configuration.
+
 ## Configure an admin user
 
 Azure Chat provides a reporting feature that allows admins to view chat sessions from users. The reporting pages in the application are only available to an admin user. To configure the admin user create or update the `ADMIN_EMAIL_ADDRESS` config setting locally and on Azure App Service with the email address or addresses of the user(s) who will use the admin report functionality.
 
-Multiple email addresses can be added, separated by commas - but it is not possible to specify a security group. For example:
+Multiple email addresses can be added here, separated by commas - but it is not possible to specify a security group.
+
+Example:
 
 ```bash
 # Update your admin email addresses - comma separated (add dev@localhost for local admin)
 [email protected],[email protected]
 ```
 
-[Next](/docs/6-chat-over-file.md)
+## Continue to the next step...
+
+👉 [Next: Deploy to Azure](./4-deploy-to-azure.md)

docs/4-deploy-to-azure.md

@@ -4,7 +4,7 @@ The following steps describes how the application can be deployed to Azure App s
 
 ## 🧬 Fork the repository
 
-Fork this repository to your own organisation so that you can execute GitHub Actions against your own Azure Subscription.
+If you haven't already, fork this repository to your own organisation so that you can execute GitHub Actions against your own Azure Subscription. This allows you to edit the code, customise it to your needs, and maintain control over the deployment process.
 
 ## 🗝️ Configure secrets in your GitHub repository
 
@@ -37,4 +37,6 @@ Once the secrets are configured, the GitHub Actions will be triggered for every
 
 ![Workflow screenshot](/docs/images/runworkflow.png)
 
-[Next](/docs/5-add-identity.md)
+## Continue to the next step...
+
+👉 [Next: Chatting with your file](./5-chat-over-file.md)

docs/6-chat-over-file.md → docs/5-chat-over-file.md

@@ -1,6 +1,6 @@
 # 📃 Chatting With Your File
 
-There are multiple ways you can integrate chat with your data in this guide you will learn how to enable users to upload a file through Azure Chat and engage in chat discussions related to the file contents.
+There are multiple ways you can integrate chat-with-your-data, in this guide you will learn how to enable users to upload a file through Azure Chat and engage in chat discussions related to the file contents.
 
 1. This approach is simple and easy to use.
 2. File contents are indexed and maintained within the chat interface and are only available for the current chat session by the current user.
@@ -89,4 +89,6 @@ With the help of the Extensions feature you can bring your own Azure AI Search i
 
 5. Save the function and publish the extension.
 
-[Next](/docs/6-persona.md)
+## Continue to the next step...
+
+👉 [Next: Personas](./6-persona.md)

docs/6-persona.md

@@ -51,4 +51,6 @@ You can now use this persona in your conversations.
 
 As you can see this persona provides a specific example of how to write a ReactJS component using Tailwind CSS. You can now use this persona to create ReactJS components and the response will be in line with the above format.
 
-[Next](/docs/8-extensions.md)
+## Continue to the next step...
+
+👉 [Next: Extensions](./7-extensions.md)

docs/8-extensions.md → docs/7-extensions.md

@@ -263,4 +263,6 @@ In this example you will be able to create and update GitHub Issues using the [G
 
 6.  **Publish**: Publish the extension to make it available to use in your conversations. Publish is an admin-only feature. If you are not an admin you will not see the publish button.
 
-[Next](/docs/9-environment-variables.md)
+## Continue to the next step...
+
+👉 [Next: Environment Variables](./8-environment-variables.md)

docs/8-environment-variables.md

@@ -0,0 +1,7 @@
+# 🔑 Environment Variables
+
+Refer to the [`.env.example`](../src/.env.example) file for the required environment variables. For local development, these should be copied to a new file named `.env.local` in the `src` directory.
+
+## Continue to the next step...
+
+👉 [Next: Managed Identities](./9-managed-identities.md)

docs/10-managed-identities.md → docs/9-managed-identities.md

@@ -52,8 +52,10 @@ To deploy the application to Azure App Service with Managed Identities, follow t
      ```powershell
      PS> .\scripts\appreg_setup.ps1
      ```
-   - You can now refer to the documentation to [run Azure Chat locally](3-run-locally.md).
+   - You can now refer to the documentation to [run Azure Chat locally](2-run-locally.md).
 
 ## Conclusion
 
 By leveraging Managed Identities, you enhance the security posture of your Azure Chat deployment while simplifying secret management and access control. This guide outlines the security advantages and highlights the necessary parameter changes to ensure a secure and efficient production setup. For more details, review the complete code and configurations available in the repository's `infra` directory.
+
+🏁 [Back to README](../README.md)