Merge pull request #199 from SSDALab/anshul-infra-docs-reconciliation

Add Pulumi infrastructure page to docs site

Author: ihsankahveci

docs/about/project-overview.md

@@ -36,6 +36,7 @@ Key capabilities:
 | Auth | Twilio Verify (OTP), JWT |
 | Permissions | CASL (role + attribute-based) |
 | Hosting | Azure App Service |
+| Infrastructure | Pulumi (TypeScript), Azure |
 | QR Scanning | Html5QrcodeScanner, QRCodeCanvas |
 
 ## Open Source and Reuse

docs/getting-started/getting-started.md

@@ -7,7 +7,7 @@
 - **GitHub** — to fork the repository and use GitHub Actions for CI/CD. [Fork the repository](https://github.com/SSDALab/respondent-driven-sampling/fork).
 - **MongoDB** — all survey data is stored in MongoDB. [MongoDB Atlas](https://www.mongodb.com/atlas) (free M0 tier) is recommended. The connection string (`MONGO_URI`) and database name (`MONGO_DB_NAME`) come from the chosen provider.
 - **Twilio** — OTP authentication for volunteer logins via Twilio Verify. Requires `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, and a Verify service SID (`TWILIO_VERIFY_SID`). `TWILIO_PHONE_NUMBER` is only needed for outbound bulk SMS.
-- **Azure App Service** (or any Node.js host) — King County uses Azure; see [Deployment](../how-to/deployment.md) for specifics.
+- **Azure App Service** (or any Node.js host) — King County uses Azure; see [Infrastructure](../how-to/infrastructure.md) for provisioning with Pulumi and [Deployment](../how-to/deployment.md) for deploying application code.
 
 **Local tools:**
 
@@ -122,4 +122,4 @@ For a pre-deployment end-to-end test, see the checklist in [Setting Up a Survey]
 
 ## 8. Deploy
 
-See [Deployment](../how-to/deployment.md) for Azure App Service instructions.
+To deploy to Azure App Service, first provision the required Azure resources (see [Infrastructure](../how-to/infrastructure.md)), then deploy the application code (see [Deployment](../how-to/deployment.md)).

docs/how-to/deployment.md

@@ -2,6 +2,9 @@
 
 This page covers deploying the RDS App to Azure App Service, the hosting platform used by King County. Complete the [Getting Started](../getting-started/getting-started.md) guide before proceeding.
 
+!!! tip "Need to provision Azure resources first?"
+    If the Azure Resource Group, MongoDB cluster, App Service Plan, and Web App do not exist yet, see [Infrastructure](infrastructure.md) to provision them with Pulumi before deploying application code.
+
 The app is a monorepo: the React frontend (`client/`) is built to static files, copied into the `server/` folder, and served by the Express backend as a single Node.js service.
 
 ## Deployment via GitHub Actions (recommended)
@@ -60,7 +63,9 @@ cp -r client/dist server/dist
 
 ## Environment Variables in Production
 
-On Azure App Service, environment variables are set as **Application settings** (not in a `.env` file):
+On Azure App Service, environment variables are set as **Application settings** (not in a `.env` file).
+
+If the infrastructure was provisioned with Pulumi (see [Infrastructure](infrastructure.md)), these settings are configured automatically during `pulumi up`. Otherwise, set them manually:
 
 Azure Portal > App Service > **Configuration** > **Application settings** > add each variable as a key-value pair > Save > restart the service.
 

docs/how-to/infrastructure.md

@@ -0,0 +1,120 @@
+# Infrastructure Provisioning
+
+The `infra/` directory contains a [Pulumi](https://www.pulumi.com/) project (TypeScript) that provisions all Azure resources required to run the RDS App. No Pulumi Cloud account is required — state is stored locally.
+
+## What Gets Created
+
+Running `pulumi up` provisions four Azure resources:
+
+| Resource | Purpose |
+|---|---|
+| **Resource Group** | Logical container for all RDS resources |
+| **MongoDB vCore Cluster** (Cosmos DB) | Application database |
+| **App Service Plan** (Linux) | Compute plan for the web app |
+| **Web App** (Node.js on Linux) | Hosts the Express server and React frontend |
+
+Pulumi also configures the Web App's **Application settings** (environment variables) automatically, including `MONGO_URI`, `AUTH_SECRET`, and the Twilio credentials. See [Environment Variables](../reference/environment-variables.md) for the meaning of each variable.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) (>=20.17.0)
+- [Pulumi CLI](https://www.pulumi.com/docs/install/)
+- [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)
+- An Azure subscription
+
+## Quick Start
+
+From the repository root:
+
+```bash
+# 1. Install dependencies
+cd infra
+npm install
+
+# 2. Log in to Azure
+az login
+
+# 3. Use local Pulumi state (no account needed)
+pulumi login --local
+
+# 4. Create a stack
+pulumi stack init prod
+
+# 5. Set required config
+pulumi config set location westus2
+pulumi config set resourceGroupName my-rds-rg
+pulumi config set mongoClusterName my-rds-db
+pulumi config set mongoDbName main
+pulumi config set appServicePlanName my-rds-plan
+pulumi config set webAppName my-rds-app
+pulumi config set skuName B1
+
+# 6. Set secrets
+pulumi config set --secret mongoAdminLogin <your-admin-user>
+pulumi config set --secret mongoAdminPassword <your-admin-password>
+pulumi config set --secret authSecret <your-auth-secret>
+pulumi config set --secret twilioAccountSid <your-sid>
+pulumi config set --secret twilioAuthToken <your-token>
+pulumi config set --secret twilioVerifySid <your-verify-sid>
+
+# 7. Deploy
+pulumi up
+```
+
+!!! warning "Secrets"
+    `mongoAdminPassword`, `authSecret`, and the Twilio credentials contain sensitive values. Always use `pulumi config set --secret` so they are encrypted in the stack state file.
+
+## Config Reference
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `resourceGroupName` | Yes | — | Azure Resource Group name |
+| `location` | Yes | — | Azure region (e.g. `westus2`) |
+| `mongoClusterName` | Yes | — | MongoDB vCore cluster name |
+| `mongoDbName` | Yes | — | MongoDB database name (e.g. `main`) |
+| `appServicePlanName` | Yes | — | App Service Plan name |
+| `webAppName` | Yes | — | Web App name (globally unique) |
+| `skuName` | Yes | — | App Service Plan SKU (e.g. `B1`, `P1v2`) |
+| `mongoAdminLogin` | Yes (secret) | — | MongoDB admin username |
+| `mongoAdminPassword` | Yes (secret) | — | MongoDB admin password |
+| `authSecret` | Yes (secret) | — | Auth secret for JWT signing |
+| `twilioAccountSid` | Yes (secret) | — | Twilio Account SID |
+| `twilioAuthToken` | Yes (secret) | — | Twilio Auth Token |
+| `twilioVerifySid` | Yes (secret) | — | Twilio Verify Service SID |
+| `nodeVersion` | No | `22-lts` | Node.js version for App Service |
+| `nodeEnv` | No | `production` | `NODE_ENV` value |
+| `mongoServerVersion` | No | `8.0` | MongoDB server version |
+| `mongoSku` | No | `M20` | MongoDB vCore cluster SKU |
+| `mongoDiskSizeGb` | No | `128` | MongoDB disk size in GB |
+
+!!! note "App settings managed by Pulumi"
+    When infrastructure is provisioned with Pulumi, the Web App's Application settings (`MONGO_URI`, `MONGO_DB_NAME`, `AUTH_SECRET`, Twilio credentials, etc.) are set automatically. There is no need to configure them manually in the Azure Portal.
+
+## Importing Existing Resources
+
+If Azure resources already exist (e.g. from a previous Terraform setup), they can be imported instead of recreated:
+
+1. Find each resource's Azure ID (from the Azure Portal or `az` CLI).
+2. Add `{ import: "<azure-resource-id>" }` as the third argument to each Pulumi resource constructor in `index.ts`.
+3. Run `pulumi up` — Pulumi adopts the resources without modifying them.
+4. Remove the `import` options and run `pulumi up` again to verify no changes are detected.
+
+Import order: Resource Group → MongoDB Cluster → App Service Plan → Web App.
+
+## Tear Down
+
+```bash
+pulumi destroy
+pulumi stack rm prod
+```
+
+## Troubleshooting
+
+- **`az login` errors** — Verify `az account show` returns a valid subscription. Set the `ARM_SUBSCRIPTION_ID` environment variable if needed.
+- **Name conflicts** — `mongoClusterName` and `webAppName` must be globally unique across Azure.
+- **SKU not available** — Some SKUs are region-specific. Try `B1` or `P1v2` in the chosen region.
+- **Node version format** — Use `22-lts` (not `v22` or `22.x`). This maps to `NODE|22-lts` in the App Service config.
+
+---
+
+After provisioning, proceed to [Deployment](deployment.md) to push the application code to the new Azure App Service.

docs/reference/architecture.md

@@ -32,6 +32,7 @@ respondent-driven-sampling/
 ├── client/          # React SPA (Vite + TypeScript + MUI)
 ├── server/          # Express API (TypeScript + MongoDB)
 ├── docs/            # Documentation source (this site)
+├── infra/           # Azure infrastructure (Pulumi + TypeScript)
 ├── mkdocs.yml       # MkDocs configuration
 └── .github/         # CI/CD workflows, issue templates
 ```
@@ -133,6 +134,8 @@ Permissions are defined in `server/src/permissions/abilityBuilder.ts` and the sa
 
 ## Deployment Architecture
 
+Azure resources (Resource Group, MongoDB vCore cluster, App Service Plan, and Web App) are provisioned via Pulumi in the `infra/` directory. See [Infrastructure](../how-to/infrastructure.md) for setup instructions.
+
 In production (Azure App Service):
 
 ```

docs/reference/environment-variables.md

@@ -33,6 +33,10 @@ Common timezone values: `America/Los_Angeles`, `America/Denver`, `America/Chicag
 
 ## Production Setup on Azure
 
-On Azure App Service, environment variables are set as **Application settings** rather than in a `.env` file:
+On Azure App Service, environment variables are set as **Application settings** rather than in a `.env` file.
+
+If the infrastructure was provisioned with Pulumi, these variables are configured automatically as App Service settings via `infra/index.ts`. See [Infrastructure](../how-to/infrastructure.md) for details.
+
+For manual configuration:
 
 Azure Portal → App Service → Configuration → Application settings → add each variable as a key-value pair → Save → restart the service.

infra/getting-started.md

@@ -1,3 +1,5 @@
+> **Canonical docs:** [Infrastructure Provisioning](https://ssdlab.github.io/respondent-driven-sampling/how-to/infrastructure/) — this file is a quick-reference for the `infra/` directory; the full documentation lives on the docs site.
+
 # RDS Infrastructure (Pulumi + Azure)
 
 Deploy the full Azure stack for the Respondent-Driven Sampling app using **Pulumi with TypeScript**.

mkdocs.yml

@@ -50,6 +50,7 @@ nav:
 
   - How-To:
       - Deployment: how-to/deployment.md
+      - Infrastructure: how-to/infrastructure.md
       - Setting Up a Survey: how-to/setting-up-a-survey.md
       - Adding Survey Locations: how-to/adding-survey-locations.md
       - Debugging: how-to/debugging.md