Skip to content

Commit

Permalink
split up documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@thivy
thivy committed Aug 7, 2023
1 parent 71f7c28 commit b6a82cb
Show file tree
Hide file tree
Showing 8 changed files with 304 additions and 302 deletions.
313 changes: 11 additions & 302 deletions README.md
View file

Large diffs are not rendered by default.

79 changes: 79 additions & 0 deletions docs/add-Identity.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# 🪪 Add an identity provider

Once the deployment is complete, you will need to add an identity provider to authenticate your app.

⚠️ Note: Only one of the identity provider is required below.

## GitHub Authentication provider

We'll create two GitHub apps: one for testing locally and another for production.

#### 🟡 Development app setup

1. Navigate to GitHub OAuth Apps setup https://github.com/settings/developers
2. Create a `New OAuth App` https://github.com/settings/applications/new
3. Fill in the following details

```
Application name: Azure ChatGPT DEV Environment
Homepage URL: http://localhost:3000
Authorization callback URL: http://localhost:3000/api/auth/callback/github
```

#### 🟢 Production app setup

1. Navigate to GitHub OAuth Apps setup https://github.com/settings/developers
2. Create a `New OAuth App` https://github.com/settings/applications/new
3. Fill in the following details

```
Application name: Azure ChatGPT Production
Homepage URL: https://YOUR-WEBSITE-NAME.azurewebsites.net
Authorization callback URL: https://YOUR-WEBSITE-NAME.azurewebsites.net/api/auth/callback/github
```

⚠️ After completing app setup, ensure your environment variables locally and on Azure App Service are up to date.

```
# GitHub OAuth app configuration
AUTH_GITHUB_ID=
AUTH_GITHUB_SECRET=
```

## Azure AD Authentication provider

#### 🟡 Development app setup

1. Navigate to Azure AD Apps setup https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps
2. Create a `New Registration` https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/CreateApplicationBlade/quickStartType~/null/isMSAApp~/false
3. Fill in the following details

```
Application name: Azure ChatGPT DEV Environment
Supported account types: Accounts in this organizational directory only
Redirect URI Platform: Web
Redirect URI: http://localhost:3000/api/auth/callback/azure-ad
```

#### 🟢 Production app setup

1. Navigate to Azure AD Apps setup https://portal.azure.com/#view/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/~/RegisteredApps
2. Create a `New Registration` https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/CreateApplicationBlade/quickStartType~/null/isMSAApp~/false
3. Fill in the following details

```
Application name: Azure ChatGPT Production
Supported account types: Accounts in this organizational directory only
Redirect URI Platform: Web
Redirect URI: https://YOUR-WEBSITE-NAME.azurewebsites.net/api/auth/callback/azure-ad
```

⚠️ After completing app setup, ensure your environment variables locally and on Azure App Service are up to date.

```
# Azure AD OAuth app configuration
AZURE_AD_CLIENT_ID=
AZURE_AD_CLIENT_SECRET=
AZURE_AD_TENANT_ID=
```
68 changes: 68 additions & 0 deletions docs/chat-over-file.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
# 📃 Chatting with your unstructured data

Users can utilise this functionality to upload their PDF files through the portal and engage in chat discussions related to the content of those files.

### Setup Azure Cognitive Search index

1. Create an index on Azure Cognitive Search with the following schema. You can use the Azure portal to create the following [indexes](https://learn.microsoft.com/en-us/azure/search/vector-search-how-to-create-index?tabs=portal-add-field%2Cpush)

```
{
"name": "azure-chatgpt",
"fields": [
{
"name": "id",
"type": "Edm.String",
"key": true,
"filterable": true
},
{
"name": "user",
"type": "Edm.String",
"searchable": true,
"filterable": true
},
{
"name": "pageContent",
"searchable": true,
"type": "Edm.String"
},
{
"name": "metadata",
"type": "Edm.String"
},
{
"name": "embedding",
"type": "Collection(Edm.Single)",
"searchable": true,
"filterable": false,
"sortable": false,
"facetable": false,
"retrievable": true,
"analyzer": "",
"dimensions": 1536,
"vectorSearchConfiguration": "vectorConfig"
}
],
"vectorSearch": {
"algorithmConfigurations": [
{
"name": "vectorConfig",
"kind": "hnsw"
}
]
}
}
```

2. After the index has been created, proceed to modify the env.local file with the appropriate Azure Cognitive Search variables.
3. At this point, you have the capability to generate a fresh chat session, opting for the `file chat` type to start uploading of a PDF file.
4. Upon the successful completion of the file upload, you are now able to commence the conversation using the provided text box.
5. Additionally, it is possible to start a new chat thread, and chat with the previous file that was uploaded

### Things to consider:

1. Central place maintain uploaded files
2. Currently only PDF files are supported, add additional file types
3. A way to delete indexed documents if the chat thread is deleted
4. Integrate [Azure Document Intelligence](https://azure.microsoft.com/en-us/products/ai-services/ai-document-intelligence) to extract better information from files
36 changes: 36 additions & 0 deletions docs/deployto-azure.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# ☁️ Deploy to Azure - GitHub Actions

### 🧬 Fork the repository

Fork this repository to your own organisation so that you can execute GitHub Actions against your own Azure Subscription.

### 🗝️ Configure secrets in your GitHub repository

### 1. AZURE_CREDENTIALS

The GitHub workflow requires a secret named `AZURE_CREDENTIALS` to authenticate with Azure. The secret contains the credentials for a service principal with the Contributor role on the resource group containing the container app and container registry.

1. Create a service principal with the Contributor role on the resource group that contains the Azure App Service.

```
az ad sp create-for-rbac
--name <NAME OF THE CREDENTIAL> --role contributor --scopes /subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP> --sdk-auth --output json
```

2. Copy the JSON output from the command.

3. In the GitHub repository, navigate to Settings > Secrets > Actions and select New repository secret.

4. Enter `AZURE_CREDENTIALS` as the name and paste the contents of the JSON output as the value.

5. Select **Add secret**.

### 2. AZURE_APP_SERVICE_NAME

Under the same repository secrets add a new variable `AZURE_APP_SERVICE_NAME` to deploy to your Azure Web app. The value of this secret is the name of your Azure Web app e.g. `my-web-app-name` from the domain https://my-web-app-name.azurewebsites.net/

### 🔄 Run GitHub Actions

Once the secrets are configured, the GitHub Actions will be triggered for every code push to the repository. Alternatively, you can manually run the workflow by clicking on the "Run Workflow" button in the Actions tab in GitHub.

![](/images/runworkflow.png)
24 changes: 24 additions & 0 deletions docs/environment-variables.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# 🔑 Environment variables

Below are the required environment variables, to be added to the Azure Portal or in the `.env.local` file.

| App Setting | Value | Note |
| ----------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| AZURE_OPENAI_API_KEY | | API keys of your Azure OpenAI resource |
| AZURE_OPENAI_API_INSTANCE_NAME | | the name of your Azure OpenAI resource |
| AZURE_OPENAI_API_DEPLOYMENT_NAME | | The name of your model deployment |
| AZURE_OPENAI_API_VERSION | 2023-03-15-preview | API version when using gpt chat |
| AUTH_GITHUB_ID | | Client ID of your GitHub OAuth application |
| AUTH_GITHUB_SECRET | | Client Secret of your GitHub OAuth application |
| NEXTAUTH_SECRET | | Used to encrypt the NextAuth.js JWT, and to hash email verification tokens. **This set by default as part of the deployment template** |
| NEXTAUTH_URL | | Current webs hosting domain name with HTTP or HTTPS. **This set by default as part of the deployment template** |
| AZURE_COSMOSDB_URI | | URL of the Azure CosmosDB |
| AZURE_COSMOSDB_KEY | | API Key for Azure Cosmos DB |
| AZURE_AD_CLIENT_ID | | The client id specific to the application |
| AZURE_AD_CLIENT_SECRET | | The client secret specific to the application |
| AZURE_AD_TENANT_ID | | The organisation Tenant ID |
| **Azure Cognitive Search is optional for Azure ChatGPT. This is only required for chat over file feature.** |
| AZURE_SEARCH_API_KEY | | API Key of Azure Cognitive search |
| AZURE_SEARCH_NAME | https://AZURE_SEARCH_NAME.search.windows.net | The deployment name of your Azure Cognitive Search |
| AZURE_SEARCH_INDEX_NAME | | The index name with [vector search](https://learn.microsoft.com/en-us/azure/search/vector-search-overview) enabled |
| AZURE_SEARCH_API_VERSION | 2023-07-01-Preview | API version which supports vector search 2023-07-01-Preview |
30 changes: 30 additions & 0 deletions docs/introduction.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
# 📘 Prerequisites

1. [Azure OpenAI](https://azure.microsoft.com/en-us/products/cognitive-services/openai-service/): To deploy and run ChatGPT on Azure, you'll need an Azure subscription with access to the Azure OpenAI service. Request access [here](https://customervoice.microsoft.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR7en2Ais5pxKtso_Pz4b1_xUOFA5Qk1UWDRBMjg0WFhPMkIzTzhKQ1dWNyQlQCN0PWcu). Once you have access, follow the instructions in this [link](https://learn.microsoft.com/en-us/azure/cognitive-services/openai/how-to/create-resource?pivots=web-portal) to deploy the gpt-35-turbo or gpt-4 models.

2. Setup GitHub or Azure AD for Authentication:
The [add an identity provider](https://github.com/oliverlabs/azurechatgpt#-add-an-identity-provider) 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/)

# 👋🏻 Introduction

Azure ChatGPT is built with the following technologies.

[Node.js 18](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

[NextAuth.js](https://next-auth.js.org/): configurable authentication framework for Next.js 13

[LangChain JS](https://www.langchain.com/): AI orchestration layer to build intelligent apps

[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 App Service](https://learn.microsoft.com/en-us/azure/app-service/): fully managed platform-as-a-service (PaaS) for hosting web applications, REST APIs, and mobile back ends.

![](/images/architecture.png)
9 changes: 9 additions & 0 deletions docs/provision-azure-resources.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# 💙 One click - Provision Azure resources

[![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://aka.ms/anzappazurechatgpt)

Click on the Deploy to Azure button and configure your settings in the Azure Portal as described in the [Environment variables](#-environment-variables) section.

⚠️ Note: This will only create azure resources. Follow the [deploy to Azure section](#-deploy-to-azure---github-actions) to build and deploy Azure ChatGPT.

Please see the [section below](#-add-an-identity-provider) for important information about adding authentication to your app.
47 changes: 47 additions & 0 deletions docs/run-locally.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# 👨🏻‍💻 Run from your local machine

Clone this repository locally or fork to your Github account. Run all of the the steps below from the "src" directory.

1. Make sure you deploy an instance of Cosmos DB in your Azure Subscription
2. Create a new file named `.env.local` to store the environment variables add the following variables.

**Please note:**

- Do not use double-quotes and do not delete any of the variables.
- Make sure that `NEXTAUTH_URL=http://localhost:3000` has no comments in the same line.

```
# Azure OpenAI configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_API_INSTANCE_NAME=
AZURE_OPENAI_API_DEPLOYMENT_NAME=
AZURE_OPENAI_API_VERSION=
# GitHub OAuth app configuration
AUTH_GITHUB_ID=
AUTH_GITHUB_SECRET=
# Azure AD OAuth app configuration
AZURE_AD_CLIENT_ID=
AZURE_AD_CLIENT_SECRET=
AZURE_AD_TENANT_ID=
# When deploying to production,
# set the NEXTAUTH_URL environment variable to the canonical URL of your site.
# More information: https://next-auth.js.org/configuration/options
NEXTAUTH_SECRET=
NEXTAUTH_URL=http://localhost:3000
AZURE_COSMOSDB_URI=
AZURE_COSMOSDB_KEY=
```

4. change the active directory to be `src`
5. Install npm packages by running `npm install`
6. Start the project by running `npm run dev`

You should now be prompted to login with your chosen OAuth provider. Once successfully logged in, you can start creating new conversations.

![](/images/chat-home.png)
![](/images/chat-history.png)

0 comments on commit b6a82cb

Please sign in to comment.