Skip to content

Commit e0b467f

Browse files
VishalS-MicrosoftVishalS-Microsoft
committed
docs: Enhance local development setup guide with detailed instructions and prerequisites
1 parent 2a5b8b8 commit e0b467f

File tree

1 file changed

+224
-13
lines changed

1 file changed

+224
-13
lines changed

‎docs/LocalDevelopmentSetup.md‎

Lines changed: 224 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,75 @@
11
# Local Development Setup Guide
22

3-
Follow the steps below to set up and run the **Document-Generation-Solution-Accelerator** locally.
3+
This guide provides comprehensive instructions for setting up the Document Generation Solution Accelerator for local development across Windows and Linux platforms.
44

5+
## Important Setup Notes
56

7+
### Multi-Service Architecture
68

7-
## Prerequisites
9+
This application consists of **two separate services** that run independently:
10+
11+
2. **Backend API** - REST API server for the frontend
12+
3. **Frontend** - React-based user interface
13+
14+
> **⚠️ Critical: Each service must run in its own terminal/console window**
15+
>
16+
> - **Do NOT close terminals** while services are running
17+
> - Open **2 separate terminal windows** for local development
18+
> - Each service will occupy its terminal and show live logs
19+
20+
21+
### Path Conventions
22+
23+
**All paths in this guide are relative to the repository root directory:**
24+
25+
```bash
26+
document-generation-solution-accelerator/ ← Repository root (start here)
27+
├── src/
28+
│ ├── .venv/ ← Python virtual environment
29+
│ ├── backend/
30+
│ │ ├── api/ ← API endpoints and routes
31+
│ │ ├── auth/ ← Authentication modules
32+
│ │ ├── helpers/ ← Utility and helper functions
33+
│ │ ├── history/ ← Chat/session history management
34+
│ │ ├── security/ ← Security-related modules
35+
│ │ └── settings.py ← Backend configuration
36+
│ ├── frontend/
37+
│ │ ├── .venv/ ← Node.js dependencies
38+
│ │ ├── node_modules/
39+
│ │ ├── src/ ← React/TypeScript source
40+
│ │ └── package.json ← Frontend dependencies
41+
│ ├── static/ ← Static web assets
42+
│ ├── tests/ ← Unit and integration tests
43+
│ ├── app.py ← Main Flask application entry point
44+
│ ├── .env ← Main application config file
45+
│ └── requirements.txt ← Python dependencies
46+
├── scripts/
47+
│ ├── prepdocs.py ← Document processing script
48+
│ ├── auth_init.py ← Authentication setup
49+
│ ├── data_preparation.py ← Data pipeline scripts
50+
│ └── config.json ← Scripts configuration
51+
├── infra/
52+
│ ├── main.bicep ← Main infrastructure template
53+
│ ├── modules/ ← Bicep modules
54+
│ ├── scripts/ ← Infrastructure scripts
55+
│ └── main.parameters.json ← Deployment parameters
56+
├── docs/ ← Documentation (you are here)
57+
└── tests/ ← End-to-end tests
58+
└── e2e-test/
59+
```
60+
61+
**Before starting any step, ensure you are in the repository root directory:**
62+
63+
```bash
64+
# Verify you're in the correct location
65+
pwd # Linux/macOS - should show: .../document-generation-solution-accelerator
66+
Get-Location # Windows PowerShell - should show: ...\document-generation-solution-accelerator
67+
68+
# If not, navigate to repository root
69+
cd path/to/document-generation-solution-accelerator
70+
```
71+
72+
## Step 1: Prerequisites - Install Required Tools
873

974
Install these tools before you start:
1075
- [Visual Studio Code](https://code.visualstudio.com/) with the following extensions:
@@ -19,9 +84,64 @@ Install these tools before you start:
1984
- [Microsoft ODBC Driver 17](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server?view=sql-server-ver16) for SQL Server.
2085

2186

22-
## Setup Steps
87+
### Windows Development
88+
89+
#### Option 1: Native Windows (PowerShell)
90+
91+
```powershell
92+
# Install Python 3.12+ and Git
93+
winget install Python.Python.3.12
94+
winget install Git.Git
95+
96+
# Install Node.js for frontend
97+
winget install OpenJS.NodeJS.LTS
98+
99+
# Install uv package manager
100+
py -3.12 -m pip install uv
101+
```
102+
103+
**Note**: On Windows, use `py -3.12 -m uv` instead of `uv` for all commands to ensure you're using Python 3.12.
104+
105+
#### Option 2: Windows with WSL2 (Recommended)
106+
107+
```bash
108+
# Install WSL2 first (run in PowerShell as Administrator):
109+
# wsl --install -d Ubuntu
110+
111+
# Then in WSL2 Ubuntu terminal:
112+
sudo apt update && sudo apt install python3.12 python3.12-venv git curl nodejs npm -y
113+
114+
# Install uv
115+
curl -LsSf https://astral.sh/uv/install.sh | sh
116+
source ~/.bashrc
117+
```
118+
119+
### Linux Development
120+
121+
#### Ubuntu/Debian
122+
123+
```bash
124+
# Install prerequisites
125+
sudo apt update && sudo apt install python3.12 python3.12-venv git curl nodejs npm -y
126+
127+
# Install uv package manager
128+
curl -LsSf https://astral.sh/uv/install.sh | sh
129+
source ~/.bashrc
130+
```
131+
132+
#### RHEL/CentOS/Fedora
133+
134+
```bash
135+
# Install prerequisites
136+
sudo dnf install python3.12 python3.12-devel git curl gcc nodejs npm -y
137+
138+
# Install uv
139+
curl -LsSf https://astral.sh/uv/install.sh | sh
140+
source ~/.bashrc
141+
```
23142

24-
### Clone the Repository
143+
144+
## Step 2: Clone the Repository
25145

26146
Choose a location on your local machine where you want to store the project files. We recommend creating a dedicated folder for your development projects.
27147

@@ -42,7 +162,69 @@ Choose a location on your local machine where you want to store the project file
42162
code .
43163
```
44164

45-
## Local Setup/Deplpoyment
165+
166+
## Step 3: Development Tools Setup
167+
168+
### Visual Studio Code (Recommended)
169+
170+
#### Required Extensions
171+
172+
Create `.vscode/extensions.json` in the workspace root and copy the following JSON:
173+
174+
```json
175+
{
176+
"recommendations": [
177+
"ms-python.python",
178+
"ms-python.pylint",
179+
"ms-python.black-formatter",
180+
"ms-python.isort",
181+
"ms-vscode-remote.remote-wsl",
182+
"ms-vscode-remote.remote-containers",
183+
"redhat.vscode-yaml",
184+
"ms-vscode.azure-account",
185+
"ms-python.mypy-type-checker"
186+
]
187+
}
188+
```
189+
190+
VS Code will prompt you to install these recommended extensions when you open the workspace.
191+
192+
#### Settings Configuration
193+
194+
Create `.vscode/settings.json` and copy the following JSON:
195+
196+
```json
197+
{
198+
"python.defaultInterpreterPath": "./.venv/bin/python",
199+
"python.terminal.activateEnvironment": true,
200+
"python.formatting.provider": "black",
201+
"python.linting.enabled": true,
202+
"python.linting.pylintEnabled": true,
203+
"python.testing.pytestEnabled": true,
204+
"python.testing.unittestEnabled": false,
205+
"files.associations": {
206+
"*.yaml": "yaml",
207+
"*.yml": "yaml"
208+
}
209+
}
210+
```
211+
212+
## Step 4: Azure Authentication Setup
213+
214+
Before configuring services, authenticate with Azure:
215+
216+
```bash
217+
# Login to Azure CLI
218+
az login
219+
220+
# Set your subscription
221+
az account set --subscription "your-subscription-id"
222+
223+
# Verify authentication
224+
az account show
225+
```
226+
227+
## Step 5: Local Setup/Deplpoyment
46228

47229
Follow these steps to set up and run the application locally:
48230

@@ -73,13 +255,34 @@ APP_ENV="Dev"
73255

74256
This change is required for running the application in local development mode.
75257

76-
### 3. Start the Application
77-
- Run `start.cmd` (Windows) or `start.sh` (Linux/Mac) to:
78-
- Install backend dependencies.
79-
- Install frontend dependencies.
80-
- Build the frontend.
81-
- Start the backend server.
82-
- Alternatively, you can run the backend in debug mode using the VS Code debug configuration defined in `.vscode/launch.json`.
258+
259+
### Required Azure RBAC Permissions
260+
261+
To run the application locally, your Azure account needs the following role assignments on the deployed resources:
262+
263+
#### App Configuration Access
264+
```bash
265+
# Get your principal ID
266+
PRINCIPAL_ID=$(az ad signed-in-user show --query id -o tsv)
267+
268+
# Assign App Configuration Data Reader role
269+
az role assignment create \
270+
--assignee $PRINCIPAL_ID \
271+
--role "App Configuration Data Reader" \
272+
--scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.AppConfiguration/configurationStores/<appconfig-name>"
273+
```
274+
275+
#### Cosmos DB Access
276+
```bash
277+
# Assign Cosmos DB Built-in Data Contributor role
278+
az cosmosdb sql role assignment create \
279+
--account-name <cosmos-account-name> \
280+
--resource-group <resource-group> \
281+
--role-definition-name "Cosmos DB Built-in Data Contributor" \
282+
--principal-id $PRINCIPAL_ID \
283+
--scope "/"
284+
```
285+
> **Note**: After local deployment is complete, you need to execute the post-deployment script so that all the required roles will be assigned automatically.
83286
84287
## Running with Automated Script
85288

@@ -97,8 +300,16 @@ cd src
97300
chmod +x start.sh
98301
./start.sh
99302
```
303+
### Start the Application
304+
- Run `start.cmd` (Windows) or `start.sh` (Linux/Mac) to:
305+
- Install backend dependencies.
306+
- Install frontend dependencies.
307+
- Build the frontend.
308+
- Start the backend server.
309+
- Alternatively, you can run the backend in debug mode using the VS Code debug configuration defined in `.vscode/launch.json`.
310+
100311

101-
## Running Backend and Frontend Separately
312+
## Step 6: Running Backend and Frontend Separately
102313

103314
#### Step 1: Create Virtual Environment (Recommended)
104315

0 commit comments

Comments
 (0)