Add more docs to meet the publish requirements (#107)

## Purpose

security file
readme
etc

## Does this introduce a breaking change?
<!-- Mark one with an "x". -->
```
[ ] Yes
[x] No
```

## Pull Request Type
What kind of change does this Pull Request introduce?

<!-- Please check the one that applies to this PR using "x". -->
```
[ ] Bugfix
[ ] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[x] Documentation content changes
[ ] Other... Please describe:
```

LICENSE.md

@@ -1,21 +1,21 @@
-    MIT License
+MIT License
 
-    Copyright (c) Microsoft Corporation.
+Copyright (c) Microsoft Corporation.
 
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE

README.md

@@ -1,35 +1,138 @@
-# Lab: Deploying and running Java Applications in Azure Container Apps
+# Deploying and running Java Applications with AI in Azure Container Apps
 
-This lab teaches you how to deploy the [Spring Petclinic Microservices](https://github.com/Azure-Samples/java-microservices-aca-lab/tree/main/src) application to Azure container apps and integrate it with additional Azure services.
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Azure-Samples/java-microservices-aca-lab)
+[![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/azure-samples/java-microservices-aca-lab)
 
-## Modules
+This project shows how to deploy the [Spring Petclinic Microservices](https://github.com/Azure-Samples/java-microservices-aca-lab/tree/main/src) application with OpenAI to [Azure Container Apps](https://learn.microsoft.com/azure/container-apps/overview) and integrate it with additional Azure services, also some samples for Azure Container Apps features.
 
-This lab has modules on:
+[Features](#features) • [Gettting Started](#getting-started) • [Guidance](#guidance)
 
-* Plan a Java application migration to Azure Container Apps
-* Migrate a Spring Apps microservices application to Azure Container Apps
-* Enable monitoring and end-to-end tracing
-* Secure application secrets.
-* Protect endpoints using Web Application Firewalls
-* Secure MySQL database and Key Vault using a Private Endpoint
+![main page](./images/api-gateway-main.png)
 
-The lab is available as GitHub pages [here](https://azure-samples.github.io/java-microservices-aca-lab/)
+## Important Security Notice
+
+This template, the application code and configuration it contains, has been built to showcase Microsoft Azure specific services and tools. We strongly advise our customers not to make this code part of their production environments without implementing or enabling additional security features.  
+
+For a more comprehensive list of best practices and security recommendations for Intelligent Applications, visit [Azure security best practices and patterns](https://learn.microsoft.com/en-us/azure/security/fundamentals/best-practices-and-patterns), [Azure security baseline for Intelligent Recommendations](https://learn.microsoft.com/en-us/security/benchmark/azure/baselines/intelligent-recommendations-security-baseline)
+
+## Features
+
+The following technologies are part of the project:
+
+* Java 17
+* Maven
+* [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/)
+* [Azure Developer CLI (azd)](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/)
+
+This project provides the following features:
+
+* A [Spring Petclinic Microservices](https://github.com/Azure-Samples/java-microservices-aca-lab/tree/main/src) deployment on Azure Container Apps with AI chat agent.
+* Azure Container Apps java components ([eureka server](https://learn.microsoft.com/en-us/azure/container-apps/java-eureka-server-usage) /[config server](https://learn.microsoft.com/en-us/azure/container-apps/java-config-server-usage) / [spring boot admin](https://learn.microsoft.com/en-us/azure/container-apps/java-admin-for-spring-usage)) support.
+* [Bicep files](https://docs.microsoft.com/azure/azure-resource-manager/bicep/) for provisioning Azure resources, including Azure OpenAI, Azure Container Apps, Azure Database for MySQL - Flexible Server, Azure Container Registry, Azure Log Analytics, Azure Application Insights and RBAC roles. See [Deploy to Azure automatically](https://azure-samples.github.io/java-microservices-aca-lab/docs/06_lab_automation/06_openlab_automation.html).
+* Best practices to build [more secure](https://azure-samples.github.io/java-microservices-aca-lab/docs/07_lab_security/07_openlab_security_aca.html), [more reliable](https://azure-samples.github.io/java-microservices-aca-lab/docs/10_lab_reliable_application/10_reliable_java_aca.html) and [more flexible](https://azure-samples.github.io/java-microservices-aca-lab/docs/11_lab_scale/11_openlab_scale_aca.html) java apps on Azure Container Apps.
+* AI chat agent to take advantage of large-scale, generative AI models with deep understandings of language and code to enable new reasoning and comprehension capabilities. See [Integrate with Azure OpenAI]({% link docs/05_lab_openai/05_openlab_openai_aca.md %})
+
+![Screenshot of the chat app](./images/acalab-ai-chat.png)
+
+### Architecture Diagram
+
+![Architecture Diagram](./images/acalab-overview.png)
 
 ## Getting Started
 
+You have a few options for getting started with this template. 
+
+* [GitHub codespace](#github-codespaces)
+* [Visual Studio Code with remote containers option](#vs-code-dev-containers)
+* [Local Development](#local-environment)
+
+All the steps of this lab have been tested in the GitHub CodeSpace. This is the preferred option for running this lab!
+
+### GitHub Codespaces
+
+* Prepare the environment following the steps in [Using a GitHub codespace](https://azure-samples.github.io/java-microservices-aca-lab/install.html#using-a-github-codespace)
+* Continue with [deploying steps](#deploying)
+
+### VS Code Dev Containers
+
+* Prepare the environment following the steps in [Using Visual Studio Code with remote containers](https://azure-samples.github.io/java-microservices-aca-lab/install.html#using-a-github-codespace)
+* Continue with [deploying steps](#deploying)
+
+### Local Environment
+
+* Prepare the environment following the steps in [Install all the tools on your local machine](https://azure-samples.github.io/java-microservices-aca-lab/install.html#install-all-the-tools-on-your-local-machine)
+* Continue with [deploying steps](#deploying)
+
+### Deploying
+
+Once you've opened the project in [Codespaces](#github-codespaces), in [Dev Containers](#vs-code-dev-containers), or [locally](#local-environment), you can deploy it to Azure.
+
+* Your Azure account must have `Microsoft.Authorization/roleAssignments/write` permissions, such as [Role Based Access Control Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview), [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator), or [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner). If you don't have subscription-level permissions, you must be granted [RBAC](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#role-based-access-control-administrator-preview) for an existing resource group and [deploy to that existing group](./docs/06_lab_automation/0604.md).
+* Your Azure account also needs `Microsoft.Resources/deployments/write` permissions on the subscription level.
+
+Suggested: Both **Contributor** and **User Access Administrator** roles on the subscription.
+
+1. Login to Azure
+
+   `azd auth login`
+
+   `az login`
+
+1. Provision and deploy all the resources:
+
+   `azd up`
+
+   It will prompt you to provide an `azd` environment name (like "java-ai"), select a subscription from your Azure account, and select a [location where OpenAI is available](#region-availability) (like "eastus2"). Then it will provision the resources in your account and deploy the latest code. If you get an error or timeout with deployment, changing the location can help, as there may be availability constraints for the OpenAI resource.
+
+1. When azd has finished deploying, visit the api-gateway url and begin your experience on AI java apps.
+
+   ```text
+   INFO: Deploy finish succeed!
+   INFO: Api Gateway App url: https://api-gateway.<cluster>.<region>.azurecontainerapps.io
+   INFO: Spring Boot Admin url: https://springbootadmin-azure-java.ext.<cluster>.<region>.azurecontainerapps.io
+   ```
+
+1. When you've made any changes to the app code, you can just run:
+
+   - `azd deploy` for all services
+
+   - `azd deploy -n <service>` for single service
+
+
+
+## Guidance
+
 ### Prerequisites
 
 For running this lab you will need:
 
-- A GitHub account
-- An Azure Subscription
+* A GitHub account
+* An Azure Subscription
+
+### Region Availability
+
+1. This template uses [Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/ai-services/openai/overview) deployment mododules **gpt-4o** and **text-embedding-ada-002** which may not be available in all Azure regions. Check for [up-to-date region availability](https://learn.microsoft.com/azure/ai-services/openai/concepts/models#standard-deployment-model-availability) and select a region during deployment accordingly
+
+1. The template uses [Azure Database for MySQL - Flexible Server](https://learn.microsoft.com/en-us/azure/mysql/flexible-server/overview) version 8.0 to store data. You may select a region suite for this service. Or create a database instance manually then [Reuse existing service](https://azure-samples.github.io/java-microservices-aca-lab/docs/06_lab_automation/0604.html).
+
+  * We recommend using **East US**, **East US 2**, **North Central US**, **Sweden Central**.
+
+### Costs
+
+You can estimate the cost of this project's architecture with [Azure's pricing calculator](https://azure.microsoft.com/pricing/calculator/)
+
+* Azure Container Apps - [Consumption](https://azure.microsoft.com/en-us/pricing/details/container-apps/)
+* Azure Database for MySQL - [Flexible Server](https://azure.microsoft.com/en-us/pricing/details/mysql/)
+* Azure OpenAI Service - [Standard](https://azure.microsoft.com/en-us/pricing/details/cognitive-services/openai-service/)
+* Azure Monitor - [Analytics Logs](https://azure.microsoft.com/en-us/pricing/details/monitor/)
+
+### Security
 
-### Installation
+This template has [Managed Identity](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview) built in to eliminate the need for developers to manage these credentials.
 
-For running this lab with all the needed tooling, there are 3 options available: 
+Applications can use managed identities to obtain Microsoft Entra tokens without having to manage any credentials. Additionally, we have added a [GitHub Action tool](https://github.com/microsoft/security-devops-action) that scans the infrastructure-as-code files and generates a report containing any detected issues. To ensure best practices in your repo we recommend 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 in your repos.
 
-- Using a GitHub codespace  
-- Using Visual Studio Code with remote containers option
-- Install all the tools on your local machine
+## Resources
 
-Full installation guidance and options for running this lab can be found in the [Installation instructions](install.md).
+* Go to the lab for more details [Deploying and running Java Applications with AI in Azure Container Apps](https://azure-samples.github.io/java-microservices-aca-lab/)
+* Full installation guidance and options for running this lab can be found in the [Installation instructions](install.md).

SECURITY.md

@@ -0,0 +1,41 @@
+<!-- BEGIN MICROSOFT SECURITY.MD V0.0.8 BLOCK -->
+
+## Security
+
+Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/).
+
+If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below.
+
+## Reporting Security Issues
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report).
+
+If you prefer to submit without logging in, send email to [[email protected]](mailto:[email protected]).  If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey).
+
+You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc).
+
+Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue:
+
+  * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.)
+  * Full paths of source file(s) related to the manifestation of the issue
+  * The location of the affected source code (tag/branch/commit or direct URL)
+  * Any special configuration required to reproduce the issue
+  * Step-by-step instructions to reproduce the issue
+  * Proof-of-concept or exploit code (if possible)
+  * Impact of the issue, including how an attacker might exploit the issue
+
+This information will help us triage your report more quickly.
+
+If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs.
+
+## Preferred Languages
+
+We prefer all communications to be in English.
+
+## Policy
+
+Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd).
+
+<!-- END MICROSOFT SECURITY.MD BLOCK -->

azure.yaml

@@ -84,6 +84,8 @@ hooks:
     posix:
       shell: sh
       run: ./infra/bicep/hooks/postprovision.sh
+      interactive: true
+      continueOnError: true
 
   prepackage:
     posix:

cleanup.md

@@ -26,20 +26,26 @@ If you're not going to continue to use this lab environment, run the following c
 1. Tear down the azd environment
 
    - run `azd env list` to see all the environments
-   - run `azd down -e <env-name>` to clean up the target environment
+   - run `azd down -e <env-name> --force --purge` to clean up the target environment
 
 ## Delete environment created by manual steps
 
 1. Clean up the Azure Cognitive Services account
 
    - list the deployments
-   `az cognitiveservices account deployment list -g $RESOURCE_GROUP -n $OPEN_AI_SERVICE_NAME -o table`
+
+      `az cognitiveservices account deployment list -g $RESOURCE_GROUP -n $OPEN_AI_SERVICE_NAME -o table`
+
    - delete the deployments on by one
-   `az cognitiveservices account deployment delete -g $RESOURCE_GROUP -n $OPEN_AI_SERVICE_NAME --deployment-name <deployment-name>`
+
+      `az cognitiveservices account deployment delete -g $RESOURCE_GROUP -n $OPEN_AI_SERVICE_NAME --deployment-name <deployment-name>`
+
    - delete the Azure Cognitive Services account
-   `az cognitiveservices account delete -g $RESOURCE_GROUP -n $OPEN_AI_SERVICE_NAME`
+
+      `az cognitiveservices account delete -g $RESOURCE_GROUP -n $OPEN_AI_SERVICE_NAME`
 
 1. Delete the resource group with all the resources
+
    `az group delete --name $RESOURCE_GROUP`
 
 {: .note }

docs/06_lab_automation/0603.md

@@ -58,7 +58,9 @@ Check the failures, fix the problems and rerun `azd up` to continue the automati
    [{"code":"ResourceDeploymentFailure","target":"/subscriptions/xxx/resourceGroups/yyy/providers/Microsoft.Resources/deploymentScripts/acr-import-image","message":"The resource write operation failed to complete successfully, because it reached terminal provisioning state 'failed'.","details":[{"code":"DeploymentScriptStorageAccountWithServiceEndpointEnabled","message":"Storage account 'zzz' has firewall settings enabled which are not supported for deployment scripts. If providing subnets with managed identity, make sure the \"Allow Azure services on the trusted services list to access this storage account\" is enabled and proper RBAC is set on the given storage. Please refer to https://aka.ms/DeploymentScriptsTroubleshoot for more deployment script information."}]}]
    ```
 
-   > This happens to prepare Azure Container Registry step, failed to run the bicep deploymentScripts to prepare the placeholder image before provision services. Some securtity rules added to storage account disabled running deploymentScripts.
+   This happens to prepare Azure Container Registry step, failed to run the bicep deploymentScripts to prepare the placeholder image before provision services. 
+   > - Check if you have the `Contributor` role for the subscription.
+   > - Some securtity rules added to storage account disabled running deploymentScripts. Contract your subscription administrator for more info.
    > - Use an existed Azure Container Registry. See guide in page [Reuse existing resource]({% link docs/06_lab_automation/0604.md %})
 
 1. Run post-provision script failed