76aa2c72c5
docs: Add production deployment success documentation for Azure Static Web App docs: Create Quick Start guide for project setup and deployment instructions docs: Update README.md to include new documentation links and structure docs: Enhance User Manual with detailed portal access, roles, and AI assistance features scripts: Implement architecture diagram export script using Mermaid CLI scripts: Create script to auto-generate documentation index for easier navigation chore: Remove unused update-doc-index script
139 lines
3.9 KiB
Markdown
139 lines
3.9 KiB
Markdown
# Quick Start Guide
|
|
|
|
Fast path to get the Miracles in Motion project running, tested, and deployed.
|
|
|
|
## 1. Prerequisites
|
|
| Tool | Recommended Version | Notes |
|
|
|------|---------------------|-------|
|
|
| Node.js | 20.x / 22.x | Functions runtime Standard supports node:20; local dev can use 22 |
|
|
| npm | 10+ | Bundled with recent Node |
|
|
| Azure CLI | >= 2.60 | For infra & Static Web Apps commands |
|
|
| SWA CLI (@azure/static-web-apps-cli) | latest | Local API + front-end emulation |
|
|
| Git | latest | Source control |
|
|
| WSL2 | Enabled | Shell environment (Ubuntu recommended) |
|
|
|
|
```bash
|
|
# Verify versions
|
|
node -v
|
|
npm -v
|
|
az version
|
|
```
|
|
|
|
## 2. Clone & Install
|
|
```bash
|
|
git clone https://github.com/Miracles-In-Motion/public-web.git
|
|
cd public-web
|
|
npm install --legacy-peer-deps
|
|
cd api && npm install --legacy-peer-deps && cd ..
|
|
```
|
|
|
|
## 3. Environment Setup
|
|
Create a `.env.local` (frontend) and `api/local.settings.json` (Azure Functions) as needed.
|
|
|
|
Example `.env.local` (do NOT commit secrets):
|
|
```
|
|
VITE_API_BASE=/api
|
|
VITE_STRIPE_PUBLISHABLE_KEY=pk_test_xxx
|
|
VITE_DEFAULT_LANGUAGE=en
|
|
VITE_SUPPORTED_LANGUAGES=en,es,fr,de,zh,ar,pt,ru
|
|
```
|
|
|
|
Example `api/local.settings.json`:
|
|
```json
|
|
{
|
|
"IsEncrypted": false,
|
|
"Values": {
|
|
"AzureWebJobsStorage": "UseDevelopmentStorage=true",
|
|
"FUNCTIONS_WORKER_RUNTIME": "node"
|
|
}
|
|
}
|
|
```
|
|
|
|
## 4. Run Locally (Integrated)
|
|
Use SWA CLI to serve front-end + Functions together.
|
|
```bash
|
|
npm run build:api # Optional: compile API TypeScript
|
|
swa start http://localhost:5173 --api-location ./api --devserver-run-command "npm run dev" --api-language node
|
|
```
|
|
If you prefer two terminals:
|
|
```bash
|
|
npm run dev # Front-end (Vite)
|
|
cd api && npm start # Functions runtime
|
|
```
|
|
|
|
## 5. Testing
|
|
```bash
|
|
npm test # Front-end tests (Vitest / Testing Library)
|
|
```
|
|
Add more tests under `src/components/__tests__/` or `src/test`.
|
|
|
|
## 6. Build
|
|
```bash
|
|
npm run build # Produces front-end dist/
|
|
cd api && npm run build # Compiles Functions to dist (if configured)
|
|
```
|
|
|
|
## 7. Azure Deployment (Static Web App Standard)
|
|
```bash
|
|
# Login
|
|
az login
|
|
|
|
# Ensure resource group exists
|
|
az group create --name rg-mim-prod --location eastus2
|
|
|
|
# Create Static Web App (front-end + managed functions)
|
|
az staticwebapp create \
|
|
--name mim-prod-web-standard \
|
|
--resource-group rg-mim-prod \
|
|
--location eastus2 \
|
|
--source . \
|
|
--branch main \
|
|
--app-location / \
|
|
--output-location dist
|
|
```
|
|
|
|
To deploy updates without GitHub Actions (manual token):
|
|
```bash
|
|
TOKEN=$(az staticwebapp secrets list --name mim-prod-web-standard --resource-group rg-mim-prod --query properties.apiKey -o tsv)
|
|
swa deploy ./dist --env production --deployment-token $TOKEN
|
|
```
|
|
|
|
## 8. Custom Domain
|
|
1. Add CNAME `www` → `<defaultHostname>`.
|
|
2. Set hostname:
|
|
```bash
|
|
az staticwebapp hostname set \
|
|
--name mim-prod-web-standard \
|
|
--resource-group rg-mim-prod \
|
|
--hostname miraclesinmotion.org
|
|
```
|
|
Azure provisions SSL automatically.
|
|
|
|
## 9. Configuration (staticwebapp.config.json)
|
|
Key elements:
|
|
- `navigationFallback` ensures SPA routing.
|
|
- `globalHeaders` for security (CSP, HSTS). Adjust `Content-Security-Policy` as integrations evolve.
|
|
|
|
## 10. Useful Scripts
|
|
| Script | Purpose |
|
|
|--------|---------|
|
|
| `npm run dev` | Start Vite dev server |
|
|
| `npm test` | Run tests |
|
|
| `npm run build` | Build front-end |
|
|
| `npm run analyze` | (If defined) Bundle analysis |
|
|
|
|
## 11. Troubleshooting
|
|
| Issue | Resolution |
|
|
|-------|------------|
|
|
| 404 on portal route | Ensure hash routing `/#/portals` or SPA fallback set |
|
|
| Functions 500 error | Check `api` logs, run locally with `func start` if using standalone Functions |
|
|
| CSP blocking script | Update CSP in `staticwebapp.config.json` to allow required domain |
|
|
| Node version mismatch | Use Node 20 for SWA managed functions, 22 locally if desired |
|
|
|
|
## 12. Next Steps
|
|
- Configure GitHub Actions for CI/CD.
|
|
- Add monitoring (Application Insights) if using standalone Functions.
|
|
- Replace test Stripe keys with live keys in production.
|
|
|
|
---
|
|
Last updated: 2025-11-11 |