Skip to content

Commit 5d3f053

Browse files
hunterjamhunterjam
committed
Add comprehensive local development guide
- Create docs/LOCAL_DEPLOYMENT.md with complete environment variable reference - Include all settings from .env.template with descriptions - Add troubleshooting for RBAC and authentication issues - Move content from scripts/README.md and expand documentation - Delete redundant scripts/README.md - Update main README.md to reference new guide
1 parent 8e8fef5 commit 5d3f053

3 files changed

Lines changed: 380 additions & 242 deletions

File tree

‎content-gen/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,7 @@ BRAND_SECONDARY_COLOR=#107C10
179179

180180
## Documentation
181181

182+
- [Local Development Guide](docs/LOCAL_DEPLOYMENT.md) - Run locally for development
182183
- [AZD Deployment Guide](docs/AZD_DEPLOYMENT.md) - Deploy with Azure Developer CLI
183184
- [Manual Deployment Guide](docs/DEPLOYMENT.md) - Step-by-step manual deployment
184185
- [Image Generation Configuration](docs/IMAGE_GENERATION.md) - DALL-E 3 and GPT-Image-1 setup

‎content-gen/docs/LOCAL_DEPLOYMENT.md‎

Lines changed: 379 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,379 @@
1+
# Local Development Guide
2+
3+
This guide covers running the Content Generation Solution Accelerator locally for development and testing.
4+
5+
## Prerequisites
6+
7+
- **Python 3.11+** - Backend runtime
8+
- **Node.js 18+** - Frontend build tools
9+
- **Azure CLI** - For authentication and environment setup
10+
- **Azure Developer CLI (azd)** - Optional, for automatic environment configuration
11+
12+
### Azure Resources
13+
14+
You need access to the following Azure resources (can use an existing deployment):
15+
16+
- Azure OpenAI with GPT and image generation models deployed
17+
- Azure Cosmos DB account with database and containers
18+
- Azure Blob Storage account
19+
- Azure AI Search service (optional, for product search)
20+
21+
## Quick Start
22+
23+
### Linux/Mac
24+
25+
```bash
26+
# First time setup
27+
./scripts/local_dev.sh setup
28+
29+
# Start development servers
30+
./scripts/local_dev.sh
31+
```
32+
33+
### Windows PowerShell
34+
35+
```powershell
36+
# First time setup
37+
.\scripts\local_dev.ps1 -Command setup
38+
39+
# Start development servers
40+
.\scripts\local_dev.ps1
41+
```
42+
43+
## Environment Configuration
44+
45+
### Option 1: Generate from Azure Deployment
46+
47+
If you have an existing Azure deployment with `azd`:
48+
49+
```bash
50+
./scripts/local_dev.sh env
51+
```
52+
53+
### Option 2: Manual Configuration
54+
55+
1. Copy the environment template:
56+
```bash
57+
cp .env.template .env
58+
```
59+
60+
2. Edit `.env` with your Azure resource values (see [Environment Variables Reference](#environment-variables-reference) below)
61+
62+
## Development Commands
63+
64+
| Command | Description |
65+
|---------|-------------|
66+
| `setup` | Create virtual environment, install Python and Node.js dependencies |
67+
| `env` | Generate `.env` file from Azure resources (uses azd if available) |
68+
| `backend` | Start only the Python/Quart backend server (port 5000) |
69+
| `frontend` | Start only the Vite frontend dev server (port 3000) |
70+
| `all` | Start both backend and frontend in parallel (default) |
71+
| `build` | Build frontend for production |
72+
| `clean` | Remove cache files, node_modules, and build artifacts |
73+
74+
### Usage Examples
75+
76+
**Linux/Mac:**
77+
```bash
78+
# Full setup and start
79+
./scripts/local_dev.sh setup
80+
./scripts/local_dev.sh
81+
82+
# Start only backend (for API development)
83+
./scripts/local_dev.sh backend
84+
85+
# Start only frontend (if backend is running elsewhere)
86+
./scripts/local_dev.sh frontend
87+
88+
# Build for production
89+
./scripts/local_dev.sh build
90+
91+
# Clean up
92+
./scripts/local_dev.sh clean
93+
```
94+
95+
**Windows PowerShell:**
96+
```powershell
97+
# Full setup and start
98+
.\scripts\local_dev.ps1 -Command setup
99+
.\scripts\local_dev.ps1
100+
101+
# Start only backend
102+
.\scripts\local_dev.ps1 -Command backend
103+
104+
# Start only frontend
105+
.\scripts\local_dev.ps1 -Command frontend
106+
```
107+
108+
## Development URLs
109+
110+
| Service | URL |
111+
|---------|-----|
112+
| Frontend | http://localhost:3000 |
113+
| Backend API | http://localhost:5000 |
114+
| Health Check | http://localhost:5000/api/health |
115+
116+
The frontend Vite dev server automatically proxies `/api/*` requests to the backend.
117+
118+
## Hot Reload
119+
120+
Both servers support hot reload:
121+
- **Backend**: Uses Hypercorn with `--reload` flag
122+
- **Frontend**: Uses Vite's built-in HMR (Hot Module Replacement)
123+
124+
Changes to source files will automatically trigger a reload.
125+
126+
---
127+
128+
## Environment Variables Reference
129+
130+
### Server Configuration
131+
132+
| Variable | Default | Description |
133+
|----------|---------|-------------|
134+
| `PORT` | `5000` | Port for the Python backend API |
135+
| `WORKERS` | `4` | Number of Hypercorn worker processes |
136+
| `BACKEND_PORT` | `5000` | Alternative port variable for local dev scripts |
137+
| `FRONTEND_PORT` | `3000` | Port for the Vite dev server |
138+
139+
### Azure Authentication
140+
141+
| Variable | Required | Description |
142+
|----------|----------|-------------|
143+
| `AZURE_CLIENT_ID` | No | Azure AD application (client) ID for authentication |
144+
145+
### Azure OpenAI Configuration
146+
147+
| Variable | Required | Description |
148+
|----------|----------|-------------|
149+
| `AZURE_OPENAI_ENDPOINT` | Yes | Azure OpenAI endpoint URL (e.g., `https://your-resource.openai.azure.com/`) |
150+
| `AZURE_OPENAI_GPT_MODEL` | Yes | GPT model deployment name (e.g., `gpt-4o`, `gpt-5.1`) |
151+
| `AZURE_OPENAI_IMAGE_MODEL` | Yes | Image generation model (`dall-e-3` or `gpt-image-1`) |
152+
| `AZURE_OPENAI_GPT_IMAGE_ENDPOINT` | No | Separate endpoint for gpt-image-1 (if different from main endpoint) |
153+
| `AZURE_OPENAI_API_VERSION` | Yes | API version (e.g., `2024-06-01`) |
154+
| `AZURE_OPENAI_PREVIEW_API_VERSION` | No | Preview API version for new features |
155+
| `AZURE_OPENAI_TEMPERATURE` | No | Generation temperature (default: `0.7`) |
156+
| `AZURE_OPENAI_MAX_TOKENS` | No | Max tokens for generation (default: `2000`) |
157+
158+
### Image Generation Settings
159+
160+
| Variable | Default | Description |
161+
|----------|---------|-------------|
162+
| `AZURE_OPENAI_IMAGE_SIZE` | `1024x1024` | Image dimensions |
163+
| `AZURE_OPENAI_IMAGE_QUALITY` | `medium` | Image quality setting |
164+
165+
**DALL-E 3 Options:**
166+
- Sizes: `1024x1024`, `1024x1792`, `1792x1024`
167+
- Quality: `standard`, `hd`
168+
169+
**GPT-Image-1 Options:**
170+
- Sizes: `1024x1024`, `1536x1024`, `1024x1536`, `auto`
171+
- Quality: `low`, `medium`, `high`, `auto`
172+
173+
### Azure Cosmos DB
174+
175+
| Variable | Required | Description |
176+
|----------|----------|-------------|
177+
| `AZURE_COSMOS_ENDPOINT` | Yes | Cosmos DB endpoint URL |
178+
| `AZURE_COSMOS_DATABASE_NAME` | Yes | Database name (default: `content-generation`) |
179+
| `AZURE_COSMOS_PRODUCTS_CONTAINER` | Yes | Products container name (default: `products`) |
180+
| `AZURE_COSMOS_CONVERSATIONS_CONTAINER` | Yes | Conversations container name (default: `conversations`) |
181+
182+
### Azure Blob Storage
183+
184+
| Variable | Required | Description |
185+
|----------|----------|-------------|
186+
| `AZURE_BLOB_ACCOUNT_NAME` | Yes | Storage account name |
187+
| `AZURE_BLOB_PRODUCT_IMAGES_CONTAINER` | Yes | Container for product images (default: `product-images`) |
188+
| `AZURE_BLOB_GENERATED_IMAGES_CONTAINER` | Yes | Container for AI-generated images (default: `generated-images`) |
189+
190+
### Azure AI Search
191+
192+
| Variable | Required | Description |
193+
|----------|----------|-------------|
194+
| `AZURE_AI_SEARCH_ENDPOINT` | No | AI Search service endpoint URL |
195+
| `AZURE_AI_SEARCH_PRODUCTS_INDEX` | No | Product search index name (default: `products`) |
196+
| `AZURE_AI_SEARCH_IMAGE_INDEX` | No | Image search index name (default: `product-images`) |
197+
198+
### UI Configuration
199+
200+
| Variable | Default | Description |
201+
|----------|---------|-------------|
202+
| `UI_APP_NAME` | `Content Generation Accelerator` | Application name shown in UI |
203+
| `UI_TITLE` | `Content Generation` | Browser tab title |
204+
| `UI_CHAT_TITLE` | `Marketing Content Generator` | Chat interface title |
205+
| `UI_CHAT_DESCRIPTION` | AI-powered multimodal content generation... | Chat interface description |
206+
207+
### Brand Guidelines
208+
209+
| Variable | Default | Description |
210+
|----------|---------|-------------|
211+
| `BRAND_TONE` | `Professional yet approachable` | Brand voice tone |
212+
| `BRAND_VOICE` | `Innovative, trustworthy, customer-focused` | Brand voice characteristics |
213+
| `BRAND_PRIMARY_COLOR` | `#0078D4` | Primary brand color (hex) |
214+
| `BRAND_SECONDARY_COLOR` | `#107C10` | Secondary brand color (hex) |
215+
| `BRAND_IMAGE_STYLE` | `Modern, clean, minimalist...` | Image generation style guidance |
216+
| `BRAND_MAX_HEADLINE_LENGTH` | `60` | Maximum headline character length |
217+
| `BRAND_MAX_BODY_LENGTH` | `500` | Maximum body text character length |
218+
| `BRAND_REQUIRE_CTA` | `true` | Require call-to-action in content |
219+
| `BRAND_PROHIBITED_WORDS` | `cheapest,guaranteed,...` | Comma-separated list of prohibited words |
220+
| `BRAND_REQUIRED_DISCLOSURES` | `` | Comma-separated required legal disclosures |
221+
222+
### Application Settings
223+
224+
| Variable | Default | Description |
225+
|----------|---------|-------------|
226+
| `AUTH_ENABLED` | `false` | Enable Azure AD authentication |
227+
| `SANITIZE_ANSWER` | `false` | Sanitize AI responses for safety |
228+
229+
---
230+
231+
## Example .env File
232+
233+
```dotenv
234+
# Azure OpenAI
235+
AZURE_OPENAI_ENDPOINT=https://my-openai.openai.azure.com/
236+
AZURE_OPENAI_GPT_MODEL=gpt-4o
237+
AZURE_OPENAI_IMAGE_MODEL=gpt-image-1
238+
AZURE_OPENAI_GPT_IMAGE_ENDPOINT=https://my-openai.openai.azure.com
239+
AZURE_OPENAI_IMAGE_SIZE=1024x1024
240+
AZURE_OPENAI_IMAGE_QUALITY=medium
241+
AZURE_OPENAI_API_VERSION=2024-06-01
242+
243+
# Cosmos DB
244+
AZURE_COSMOS_ENDPOINT=https://my-cosmos.documents.azure.com:443/
245+
AZURE_COSMOS_DATABASE_NAME=content-generation
246+
AZURE_COSMOS_PRODUCTS_CONTAINER=products
247+
AZURE_COSMOS_CONVERSATIONS_CONTAINER=conversations
248+
249+
# Blob Storage
250+
AZURE_BLOB_ACCOUNT_NAME=mystorageaccount
251+
AZURE_BLOB_PRODUCT_IMAGES_CONTAINER=product-images
252+
AZURE_BLOB_GENERATED_IMAGES_CONTAINER=generated-images
253+
254+
# AI Search (optional)
255+
AZURE_AI_SEARCH_ENDPOINT=https://my-search.search.windows.net
256+
AZURE_AI_SEARCH_PRODUCTS_INDEX=products
257+
258+
# UI
259+
UI_APP_NAME=Content Generation Accelerator
260+
UI_TITLE=Content Generation
261+
262+
# Brand
263+
BRAND_TONE=Professional yet approachable
264+
BRAND_VOICE=Innovative, trustworthy, customer-focused
265+
BRAND_PRIMARY_COLOR=#0078D4
266+
BRAND_PROHIBITED_WORDS=cheapest,guaranteed,best in class
267+
268+
# Server
269+
PORT=5000
270+
AUTH_ENABLED=false
271+
```
272+
273+
---
274+
275+
## Utility Scripts
276+
277+
### Data Scripts
278+
279+
| Script | Description |
280+
|--------|-------------|
281+
| `load_sample_data.py` | Load sample products into Cosmos DB and images into Blob Storage |
282+
| `index_products.py` | Create and populate Azure AI Search index with product data |
283+
| `upload_images.py` | Upload images from local directory to Blob Storage |
284+
| `create_image_search_index.py` | Create image search index for visual similarity |
285+
286+
**Usage:**
287+
```bash
288+
# Load sample data
289+
python scripts/load_sample_data.py
290+
291+
# Create search index
292+
python scripts/index_products.py
293+
294+
# Upload images
295+
python scripts/upload_images.py --source ./images --container product-images
296+
```
297+
298+
### Testing Scripts
299+
300+
| Script | Description |
301+
|--------|-------------|
302+
| `test_content_generation.py` | End-to-end test for content generation pipeline |
303+
304+
**Usage:**
305+
```bash
306+
python scripts/test_content_generation.py
307+
```
308+
309+
---
310+
311+
## Troubleshooting
312+
313+
### Port Already in Use
314+
315+
```bash
316+
# Find and kill the process
317+
lsof -i :5000
318+
kill -9 <PID>
319+
320+
# Or use a different port
321+
BACKEND_PORT=8000 ./scripts/local_dev.sh backend
322+
```
323+
324+
### Virtual Environment Issues
325+
326+
```bash
327+
# Remove and recreate
328+
rm -rf .venv
329+
./scripts/local_dev.sh setup
330+
```
331+
332+
### Node Modules Issues
333+
334+
```bash
335+
# Clean and reinstall
336+
./scripts/local_dev.sh clean
337+
./scripts/local_dev.sh setup
338+
```
339+
340+
### Azure Authentication
341+
342+
```bash
343+
# Re-authenticate
344+
az login
345+
az account set --subscription <subscription-id>
346+
347+
# Verify authentication
348+
az account show
349+
```
350+
351+
### Cosmos DB Access Denied
352+
353+
Ensure your user has the "Cosmos DB Data Contributor" role:
354+
```bash
355+
az cosmosdb sql role assignment create \
356+
--resource-group <rg> \
357+
--account-name <cosmos-account> \
358+
--role-definition-id "00000000-0000-0000-0000-000000000002" \
359+
--principal-id $(az ad signed-in-user show --query id -o tsv) \
360+
--scope "/"
361+
```
362+
363+
### Storage Access Denied
364+
365+
Ensure your user has the "Storage Blob Data Contributor" role:
366+
```bash
367+
az role assignment create \
368+
--role "Storage Blob Data Contributor" \
369+
--assignee $(az ad signed-in-user show --query userPrincipalName -o tsv) \
370+
--scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Storage/storageAccounts/<storage>
371+
```
372+
373+
---
374+
375+
## Related Documentation
376+
377+
- [AZD Deployment Guide](AZD_DEPLOYMENT.md) - Deploy to Azure with `azd up`
378+
- [Manual Deployment Guide](DEPLOYMENT.md) - Step-by-step Azure deployment
379+
- [Image Generation Configuration](IMAGE_GENERATION.md) - DALL-E 3 and GPT-Image-1 setup

0 commit comments

Comments
 (0)