Merge pull request MSUSAzureAccelerators#49 from dantelmomsft/github-actions-documentation

notebook9 updated with github actions documentation

Author: pablomarin

09-Building-Apps.ipynb

@@ -1,6 +1,7 @@
 {
  "cells": [
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "1ccf7ea5-1abe-4401-a8c7-64bbfc057425",
    "metadata": {},
@@ -9,6 +10,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "78574a83-1d13-4e99-be84-ddcc5f2c011e",
    "metadata": {},
@@ -23,6 +25,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "0a8858d8-c89c-4985-9164-b79cf9c530e3",
    "metadata": {},
@@ -31,6 +34,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "3db318f3-f0f1-4328-a82e-9bb7f2a0eddf",
    "metadata": {},
@@ -48,6 +52,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "e398cb34-3735-40ca-8dbf-3c50582e2213",
    "metadata": {},
@@ -56,6 +61,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "f2905d00-c1c4-4fa8-8b4e-23c6fd0c1acc",
    "metadata": {},
@@ -68,6 +74,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "25987e8c-c5fe-45c2-8547-b0f66b3faf0d",
    "metadata": {},
@@ -76,6 +83,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "d31a7289-ca58-4bec-a977-aac3f755ea7f",
    "metadata": {},
@@ -84,6 +92,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "20c1936c-d084-4694-97eb-1ebd21fd5fe1",
    "metadata": {},
@@ -107,6 +116,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "8ba1f125-2cc7-48ca-a047-5054f2f4ed37",
    "metadata": {},
@@ -115,6 +125,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "b9cb19fc-cd64-428c-8f2b-1963ff9fc4fb",
    "metadata": {},
@@ -132,6 +143,43 @@
    ]
   },
   {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "e6f4abc9",
+   "metadata": {},
+   "source": [
+    "# Build and deploy with GitHub Actions"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "c8cc7d8e",
+   "metadata": {},
+   "source": [
+    "if you don't want to build and deploy all the components manually, a GitHub automated CI pipeline is provided in `.github/workflows/main_gptsmartsearch_apps.yml`. Some notes about the CI pipeline design:\n",
+    "- It uses a \"branch per environment approach\". The deploy environment name is computed at 'runtime' based on a branch/env-name mapping logic in the \"set environment for branch\" step (line 29). The current implemented logic maps everything to a dev like environment. Therefore on each git push on the `main branch` the pipeline is triggered trying to deploy to an environment called `Development`. For more info about GitHub environments and how to set specific env variables and secrets read [here](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment).\n",
+    "- GitHub environment variables and secrets are used to configure development environment specific configuration. They need to be configured manually in github repository settings:\n",
+    "    - `secrets.AZUREAPPSERVICE_X_PUBLISHPROFILE` is used to store the azure app service publish profile configuration securely.\n",
+    "    - `vars.AZURE_WEBAPP_X_NAME` is used to store the azure web app resource name generated during infra arm deployment.\n",
+    "- Python dependencies installation is disabled during build phase as azure web apps are currently configured with SCM_DO_BUILD_DURING_DEPLOYMENT. There is an env properties that can be used to activate dependencies resolution during build job. Just set `DO_BUILD_DURING_DEPLOYMENT : false `.\n",
+    "\n",
+    "To properly configure automated build and deploy for both backend and frontend components follow below steps:\n",
+    " \n",
+    " 1. Go to your forked repository in GitHub and create an [environment]((https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment)) called 'Development' (yes this exact name; don't change it). If you want to change the environment name, add new branches and environments  or change the current branch/env mapping you can do that, but make sure to change the pipeline code accordingly in `.github/workflows/main_gptsmartsearch_apps.yml` (starting line 29)\n",
+    " 2. Create 'Development' environment [secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) for both frontend and backend azure web apps [publish profiles]((https://learn.microsoft.com/en-us/visualstudio/azure/how-to-get-publish-profile-from-azure-app-service?view=vs-2022)). You'll need to copy paste the xml content from the .PublishSettings file into the secret value:\n",
+    "     - Create a secret with name `AZUREAPPSERVICE_BACKEND_PUBLISHPROFILE` and set the Value field to publish profile of the azure web app you created using 'Deploy to Azure' button in `apps/backend/README.md`\n",
+    "     - Create a secret with name `AZUREAPPSERVICE_FRONTEND_PUBLISHPROFILE` and set the Value field to publish profile of the azure web app you created using 'Deploy to Azure' button in `apps/frontend/README.md`\n",
+    "3. Create 'Development' environment [variables](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-an-environment) for both frontend and backend azure web app resource names:\n",
+    "    - Create a variable with name `AZURE_WEBAPP_BACKEND_NAME` and set the Value field to the azure web app resource name you created using 'Deploy to Azure' button in `apps/backend/README.md`\n",
+    "    - Create a variable with name `AZURE_WEBAPP_FRONTEND_NAME` and set the Value field to the azure web app resource name you created using 'Deploy to Azure' button in `apps/frontend/README.md`\n",
+    "4. For each commit you push check the status of the triggered pipeline in the GitHub Actions tab, you should see a pipeline has been triggered for the specific commit. If everything is ok you should see green checkmark on both build and deploy jobs in the pipeline detail like below:\n",
+    "\n",
+    "![pipeline success](./images/github-actions-pipeline-success.png)\n"
+   ]
+  },
+  {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "e0301fa7-1eb9-492a-918d-5c36ca5cce90",
    "metadata": {},
@@ -140,6 +188,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "bdcdefab-7056-4990-b938-8e82b8dd9501",
    "metadata": {},

README.md

@@ -2,6 +2,7 @@
 
 # 3 or 5 days POC VBD powered by: Azure Search + Azure OpenAI + Bot Framework + Langchain + Azure SQL + CosmosDB + Bing Search API
 [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/MSUSAzureAccelerators/Azure-Cognitive-Search-Azure-OpenAI-Accelerator?quickstart=1)
+[![Open in VS Code Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Remote%20-%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/MSUSAzureAccelerators/Azure-Cognitive-Search-Azure-OpenAI-Accelerator)
 
 Your organization requires a Multi-Channel Smart Chatbot and a search engine capable of comprehending diverse types of data scattered across various locations. Additionally, the conversational chatbot should be able to provide answers to inquiries, along with the source and an explanation of how and where the answer was obtained. In other words, you want **private and secured ChatGPT for your organization that can interpret, comprehend, and answer questions about your business data**.