Skip to content

Commit 420718b

Browse files
Roopan-MicrosoftRoopan-Microsoft
authored
Merge pull request #652 from microsoft/psl-README-change
docs: Updated README file for MACAE
2 parents 790c6a2 + fbb9ad0 commit 420718b

File tree

1 file changed

+106
-72
lines changed

1 file changed

+106
-72
lines changed

‎docs/DeploymentGuide.md‎

Lines changed: 106 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,11 @@
44

55
To deploy this solution accelerator, ensure you have access to an [Azure subscription](https://azure.microsoft.com/free/) with the necessary permissions to create **resource groups, resources, app registrations, and assign roles at the resource group level**. This should include Contributor role at the subscription level and Role Based Access Control role on the subscription and/or resource group level. Follow the steps in [Azure Account Set Up](../docs/AzureAccountSetUp.md).
66

7+
> **Note:** When you deploy this solution, you will automatically be granted access to interact with the Cosmos DB database that stores your application data. Specifically, you'll have permissions to:
8+
> - Read database information and settings
9+
> - Create, modify, and delete data storage containers (think of these as folders for organizing your data)
10+
> - Add, view, update, and remove individual data records within those containers
11+
712
Check the [Azure Products by Region](https://azure.microsoft.com/en-us/explore/global-infrastructure/products-by-region/?products=all&regions=all) page and select a **region** where the following services are available:
813

914
- [Azure AI Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/)
@@ -53,62 +58,6 @@ Upgrade commands by OS:
5358

5459
## Deployment Options & Steps
5560

56-
### Sandbox or WAF Aligned Deployment Options
57-
58-
The [`infra`](../infra) folder of the Multi Agent Solution Accelerator contains the [`main.bicep`](../infra/main.bicep) Bicep script, which defines all Azure infrastructure components for this solution.
59-
60-
By default, the `azd up` command uses the [`main.parameters.json`](../infra/main.parameters.json) file to deploy the solution. This file is pre-configured for a **sandbox environment** — ideal for development and proof-of-concept scenarios, with minimal security and cost controls for rapid iteration.
61-
62-
For **production deployments**, the repository also provides [`main.waf.parameters.json`](../infra/main.waf.parameters.json), which applies a [Well-Architected Framework (WAF) aligned](https://learn.microsoft.com/en-us/azure/well-architected/) configuration. This option enables additional Azure best practices for reliability, security, cost optimization, operational excellence, and performance efficiency, such as:
63-
64-
**Prerequisite** — Enable the Microsoft.Compute/EncryptionAtHost feature for every subscription (and region, if required) where you plan to deploy VMs or VM scale sets with `encryptionAtHost: true`. Repeat the registration steps below for each target subscription (and for each region when applicable). This step is required for **WAF-aligned** (production) deployments.
65-
66-
Steps to enable the feature:
67-
1. Set the target subscription:
68-
Run: <code>az account set --subscription "&lt;YourSubscriptionId&gt;"</code>
69-
2. Register the feature (one time per subscription):
70-
Run: <code>az feature register --name EncryptionAtHost --namespace Microsoft.Compute</code>
71-
3. Wait until registration completes and shows "Registered":
72-
Run: <code>az feature show --name EncryptionAtHost --namespace Microsoft.Compute --query properties.state -o tsv</code>
73-
4. Refresh the provider (if required):
74-
Run: <code>az provider register --namespace Microsoft.Compute</code>
75-
5. Re-run the deployment after registration is complete.
76-
77-
Note: Feature registration can take several minutes. Ensure the feature is registered before attempting deployments that require encryptionAtHost.
78-
79-
Reference: Azure Host Encryption — https://learn.microsoft.com/azure/virtual-machines/disks-enable-host-based-encryption-portal?tabs=azure-cli
80-
81-
- Enhanced network security (e.g., Network protection with private endpoints)
82-
- Stricter access controls and managed identities
83-
- Logging, monitoring, and diagnostics enabled by default
84-
- Resource tagging and cost management recommendations
85-
86-
**How to choose your deployment configuration:**
87-
88-
* Use the default `main.parameters.json` file for a **sandbox/dev environment**
89-
* For a **WAF-aligned, production-ready deployment**, copy the contents of `main.waf.parameters.json` into `main.parameters.json` before running `azd up`
90-
91-
---
92-
93-
### VM Credentials Configuration
94-
95-
By default, the solution sets the VM administrator username and password from environment variables.
96-
If you do not configure these values, a randomly generated GUID will be used for both the username and password.
97-
98-
To set your own VM credentials before deployment, use:
99-
100-
```sh
101-
azd env set AZURE_ENV_VM_ADMIN_USERNAME <your-username>
102-
azd env set AZURE_ENV_VM_ADMIN_PASSWORD <your-password>
103-
```
104-
105-
> [!TIP]
106-
> Always review and adjust parameter values (such as region, capacity, security settings and log analytics workspace configuration) to match your organization’s requirements before deploying. For production, ensure you have sufficient quota and follow the principle of least privilege for all identities and role assignments.
107-
108-
109-
> [!IMPORTANT]
110-
> The WAF-aligned configuration is under active development. More Azure Well-Architected recommendations will be added in future updates.
111-
11261
### Deployment Steps
11362

11463
Pick from the options below to see step-by-step instructions for GitHub Codespaces, VS Code Dev Containers, Local Environments, and Bicep deployments.
@@ -129,12 +78,12 @@ You can run this solution using GitHub Codespaces. The button will open a web-ba
12978

13079
2. Accept the default values on the create Codespaces page.
13180
3. Open a terminal window if it is not already open.
132-
4. Continue with the [deploying steps](#deploying-with-azd).
81+
4. Continue with the [deployment options](#deployment-options).
13382

13483
</details>
13584

13685
<details>
137-
<summary><b>Deploy in VS Code</b></summary>
86+
<summary><b>Deploy in VS Code Dev Containers</b></summary>
13887

13988
### VS Code Dev Containers
14089

@@ -146,7 +95,7 @@ You can run this solution in VS Code Dev Containers, which will open the project
14695
[![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/microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator)
14796

14897
3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window.
149-
4. Continue with the [deploying steps](#deploying-with-azd).
98+
4. Continue with the [deployment options](#deployment-options).
15099

151100
</details>
152101

@@ -171,12 +120,69 @@ If you're not using one of the above options for opening the project, then you'l
171120
azd init -t microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator/
172121
```
173122

123+
> **⚠️ Warning:** The `azd init` command will download and initialize the project template. If you run this command in a directory that already contains project files, it may override your existing changes. Only run this command once when setting up the project for the first time. If you need to update an existing project, consider using `git pull` or manually downloading updates instead.
124+
174125
3. Open the project folder in your terminal or editor.
175-
4. Continue with the [deploying steps](#deploying-with-azd).
126+
4. Continue with the [deployment options](#deployment-options).
176127

177128
</details>
178129

179-
<br/>
130+
### Deployment Options
131+
132+
The [`infra`](../infra) folder of the Multi Agent Solution Accelerator contains the [`main.bicep`](../infra/main.bicep) Bicep script, which defines all Azure infrastructure components for this solution.
133+
134+
By default, the `azd up` command uses the [`main.parameters.json`](../infra/main.parameters.json) file to deploy the solution. This file is pre-configured for a **sandbox environment** — ideal for development and proof-of-concept scenarios, with minimal security and cost controls for rapid iteration.
135+
136+
For **production deployments**, the repository also provides [`main.waf.parameters.json`](../infra/main.waf.parameters.json), which applies a [Well-Architected Framework (WAF) aligned](https://learn.microsoft.com/en-us/azure/well-architected/) configuration. This option enables additional Azure best practices for reliability, security, cost optimization, operational excellence, and performance efficiency, such as:
137+
138+
**Prerequisite** — Enable the Microsoft.Compute/EncryptionAtHost feature for every subscription (and region, if required) where you plan to deploy VMs or VM scale sets with `encryptionAtHost: true`. Repeat the registration steps below for each target subscription (and for each region when applicable). This step is required for **WAF-aligned** (production) deployments.
139+
140+
Steps to enable the feature:
141+
1. Set the target subscription:
142+
Run: <code>az account set --subscription "&lt;YourSubscriptionId&gt;"</code>
143+
2. Register the feature (one time per subscription):
144+
Run: <code>az feature register --name EncryptionAtHost --namespace Microsoft.Compute</code>
145+
3. Wait until registration completes and shows "Registered":
146+
Run: <code>az feature show --name EncryptionAtHost --namespace Microsoft.Compute --query properties.state -o tsv</code>
147+
4. Refresh the provider (if required):
148+
Run: <code>az provider register --namespace Microsoft.Compute</code>
149+
5. Re-run the deployment after registration is complete.
150+
151+
Note: Feature registration can take several minutes. Ensure the feature is registered before attempting deployments that require encryptionAtHost.
152+
153+
Reference: Azure Host Encryption — https://learn.microsoft.com/azure/virtual-machines/disks-enable-host-based-encryption-portal?tabs=azure-cli
154+
155+
- Enhanced network security (e.g., Network protection with private endpoints)
156+
- Stricter access controls and managed identities
157+
- Logging, monitoring, and diagnostics enabled by default
158+
- Resource tagging and cost management recommendations
159+
160+
**How to choose your deployment configuration:**
161+
162+
* Use the default `main.parameters.json` file for a **sandbox/dev environment**
163+
* For a **WAF-aligned, production-ready deployment**, copy the contents of `main.waf.parameters.json` into `main.parameters.json` before running `azd up`
164+
165+
---
166+
167+
### VM Credentials Configuration
168+
169+
By default, the solution sets the VM administrator username and password from environment variables.
170+
If you do not configure these values, a randomly generated GUID will be used for both the username and password.
171+
172+
To set your own VM credentials before deployment, use:
173+
174+
```sh
175+
azd env set AZURE_ENV_VM_ADMIN_USERNAME <your-username>
176+
azd env set AZURE_ENV_VM_ADMIN_PASSWORD <your-password>
177+
```
178+
179+
> [!TIP]
180+
> Always review and adjust parameter values (such as region, capacity, security settings and log analytics workspace configuration) to match your organization’s requirements before deploying. For production, ensure you have sufficient quota and follow the principle of least privilege for all identities and role assignments.
181+
182+
183+
> [!IMPORTANT]
184+
> The WAF-aligned configuration is under active development. More Azure Well-Architected recommendations will be added in future updates.
185+
180186

181187
Consider the following settings during your deployment to modify specific settings:
182188

@@ -219,6 +225,27 @@ To adjust quota settings, follow these [steps](./AzureGPTQuotaSettings.md).
219225

220226
Once you've opened the project in [Codespaces](#github-codespaces), [Dev Containers](#vs-code-dev-containers), or [locally](#local-environment), you can deploy it to Azure by following these steps:
221227

228+
#### Important: Environment Management for Redeployments
229+
230+
> **⚠️ Critical:** If you're redeploying or have deployed this solution before, you **must** create a fresh environment to avoid conflicts and deployment failures.
231+
232+
**Choose one of the following before deployment:**
233+
234+
**Option A: Create a completely new environment (Recommended)**
235+
```shell
236+
azd env new <new-environment-name>
237+
```
238+
239+
**Option B: Reinitialize in a new directory**
240+
```shell
241+
# Navigate to a new directory
242+
cd ../my-new-deployment
243+
azd init -t microsoft/Multi-Agent-Custom-Automation-Engine-Solution-Accelerator/
244+
```
245+
246+
> **💡 Why is this needed?** Azure resources maintain state information tied to your environment. Reusing an old environment can cause naming conflicts, permission issues, and deployment failures.
247+
248+
#### Deploy the solution
222249
1. Login to Azure:
223250

224251
```shell
@@ -243,8 +270,9 @@ Once you've opened the project in [Codespaces](#github-codespaces), [Dev Contain
243270

244271
- This deployment will take _4-6 minutes_ to provision the resources in your account and set up the solution with sample data.
245272
- If you encounter an error or timeout during deployment, changing the location may help, as there could be availability constraints for the resources.
273+
- **Upon successful completion**, you will see a success message indicating that all resources have been deployed, along with the application URL and next steps for uploading team configurations and sample data.
246274

247-
5. After deployment completes, you can upload Team Configurations using command printed in the terminal. The command will look like one of the following. Run the appropriate command for your shell from the project root:
275+
5. Upload Team Configurations using command printed in the terminal. The command will look like one of the following. Run the appropriate command for your shell from the project root:
248276

249277
- **For Bash (Linux/macOS/WSL):**
250278
```bash
@@ -256,7 +284,7 @@ Once you've opened the project in [Codespaces](#github-codespaces), [Dev Contain
256284
infra\scripts\Upload-Team-Config.ps1
257285
```
258286

259-
6. After deployment completes, you can index Sample Data into Search Service using command printed in the terminal. The command will look like one of the following. Run the appropriate command for your shell from the project root:
287+
6. Index Sample Data into Search Service using command printed in the terminal. The command will look like one of the following. Run the appropriate command for your shell from the project root:
260288

261289
- **For Bash (Linux/macOS/WSL):**
262290
```bash
@@ -268,7 +296,7 @@ Once you've opened the project in [Codespaces](#github-codespaces), [Dev Contain
268296
infra\scripts\Process-Sample-Data.ps1
269297
```
270298

271-
7. To upload team configurations and index sample data in one step. Run the appropriate command for your shell from the project root:
299+
7. **[Alternative]** To upload team configurations and index sample data in one step, run the appropriate command for your shell from the project root:
272300

273301
- **For Bash (Linux/macOS/WSL):**
274302
```bash
@@ -280,15 +308,25 @@ Once you've opened the project in [Codespaces](#github-codespaces), [Dev Contain
280308
infra\scripts\Team-Config-And-Data.ps1
281309
```
282310

283-
8. Once the deployment has completed successfully, open the [Azure Portal](https://portal.azure.com/), go to the deployed resource group, find the App Service, and get the app URL from `Default domain`.
284-
285-
9. When Deployment is complete, follow steps in [Set Up Authentication in Azure App Service](../docs/azure_app_service_auth_setup.md) to add app authentication to your web app running on Azure App Service
311+
8. **[Optional]** Set up authentication for your web application by following the steps in [Set Up Authentication in Azure App Service](../docs/azure_app_service_auth_setup.md).
286312

287-
10. If you are done trying out the application, you can delete the resources by running `azd down`.
313+
9. **Access your application:** Open the [Azure Portal](https://portal.azure.com/), go to your resource group, find the App Service that runs the frontend application, and get the application URL from the **Default domain** field.
288314

289315
### 🛠️ Troubleshooting
290316
If you encounter any issues during the deployment process, please refer [troubleshooting](../docs/TroubleShootingSteps.md) document for detailed steps and solutions.
291317

318+
## Next Steps
319+
Now that you've completed your deployment, you can start using the solution.
320+
321+
To help you get started, here are some [Sample Questions](./SampleQuestions.md) you can follow to try it out.
322+
323+
## Clean Up Resources
324+
If you are done trying out the application, you can delete all resources by running:
325+
326+
```shell
327+
azd down
328+
```
329+
292330
# Local setup
293331
294332
> **Note for macOS Developers**: If you are using macOS on Apple Silicon (ARM64) the DevContainer will **not** work. This is due to a limitation with the Azure Functions Core Tools (see [here](https://github.com/Azure/azure-functions-core-tools/issues/3112)).
@@ -496,7 +534,3 @@ To debug the python server in the frontend directory (frontend_server.py) and re
496534
"jinja": true
497535
}
498536
```
499-
## Next Steps
500-
Now that you've completed your deployment, you can start using the solution.
501-
502-
To help you get started, here are some [Sample Questions](./SampleQuestions.md) you can follow to try it out.

0 commit comments

Comments
 (0)