docs: added a local setup guide #245
Conversation
Vemarthula-Microsoft
requested review from
Avijit-Microsoft,
Prajwal-Microsoft,
Roopan-Microsoft,
Vinay-Microsoft and
aniaroramsft
as code owners
…nd frontend components
Vemarthula-Microsoft
requested review from
dgp10801,
nchandhi and
toherman-msft
as code owners
There was a problem hiding this comment.
Pull request overview
This PR introduces comprehensive local development documentation for the Content Processing Solution Accelerator. It provides step-by-step instructions for setting up and running the solution locally, including prerequisites, environment configuration, debugging, and troubleshooting.
Key changes:
- Added detailed setup instructions covering prerequisites, dev container usage, and Azure resource deployment
- Documented configuration steps for all three components (API, Processor, and Web frontend) with platform-specific commands
- Included comprehensive troubleshooting section addressing common development environment issues
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
docs/LocalSetupGuide.md
Outdated
| ``` | ||
|
|
||
| **Troubleshooting startup:** | ||
| - If you get "Forbidden" errors from App Configuration or Cosmos DB, ensure your Azure role assignments have propagated (wait 5-10 minutes after creating them) |
There was a problem hiding this comment.
Give the list of roles that developer needs to have as prerequisite
| --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/<resource-group>/providers/Microsoft.DocumentDB/databaseAccounts/<cosmos-name>" | ||
|
|
||
| # 3. Storage Queue Data Contributor | ||
| az role assignment create \ |
There was a problem hiding this comment.
We upload blob as well, so user might need to have Blob contributor role as well, cross check all roles that are assigned to API & Processor Container App and add missing roles
| Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser | ||
| ``` | ||
|
|
||
| ### 3.3. Install Dependencies |
There was a problem hiding this comment.
Content processing uses uv sync as package manager
docs/LocalSetupGuide.md
Outdated
| APP_CONFIG_ENDPOINT=https://<your-appconfig-name>.azconfig.io | ||
|
|
||
| # Cosmos DB endpoint from your Azure deployment | ||
| AZURE_COSMOS_ENDPOINT=https://<your-cosmos-name>.documents.azure.com:443/ |
There was a problem hiding this comment.
Are these keys AZURE_COSMOS_ENDPOINT & AZURE_COSMOS_DATABASE really required to be added in .env as they are read from App Config, check if these keys are present in App Config.
docs/LocalSetupGuide.md
Outdated
| │ │ ├── .venv/ ← Virtual environment | ||
| │ │ └── src/ | ||
| │ │ ├── main.py ← Processor entry point | ||
| │ │ └── .env.dev ← Processor config file |
There was a problem hiding this comment.
.env.dev seems to be a sample .env file, which we no need to represent here.
docs/LocalSetupGuide.md
Outdated
|
|
||
| ### 4.4. Configure Environment Variables | ||
|
|
||
| Create a `.env.dev` file (note the `.dev` suffix) in the `src/ContentProcessor/src/` directory: |
There was a problem hiding this comment.
This should be .env file utself, .env.dev does not load automatically
There was a problem hiding this comment.
Rename the file as per the standard
…anagement improvements
…mprehensive instructions for setting up the Content Processing Solution Accelerator for local development on Windows and Linux.
Purpose
This pull request introduces a comprehensive local development guide for the project. The new
LocalSetupGuide.mdfile provides step-by-step instructions for setting up the development environment, deploying resources, running and debugging the solution locally, and troubleshooting common issues. This documentation is intended to streamline onboarding and improve the developer experience.The most important changes are:
New developer documentation:
docs/LocalSetupGuide.mdfile covering prerequisites, environment setup, deployment steps, and component-specific instructions for both backend and frontend development.Environment and deployment guidance:
.envfiles, and configuring Azure resources and permissions.launch.jsonconfigurations for VS Code.Troubleshooting and support:
Does this introduce a breaking change?
Golden Path Validation
Deployment Validation
What to Check
Verify that the following are valid
Other Information