InsightForge
Customer Install Guide

Prerequisites

• Azure subscription with permission to create resource groups, Function Apps (Flex Consumption), Storage, Key Vault, and Static Web Apps.
• At least one email provider:
  • Postmark — Server API token (Servers → API Tokens). Optional: Account token (server discovery) and webhook signing secret (HMAC on ingest).
  • Azure Communication Services (optional) — an existing ACS resource for Azure-native email events. You can provide the ACS ARM resource ID at Marketplace install or connect later in Setup.
• Release package URLs — public HTTPS zips for ingest, processing, api, dashboard, and janitor (defaults in the install wizard, or pinned versions from your publisher).
• Optional Entra ID — application registration for dashboard sign-in. After deploy, add redirect URI https://<dashboard-host>/.auth/login/aad/callback using template output dashboardUrl.

Install via Azure Marketplace

1. Open the InsightForge offer in Azure Portal → Create.
2. Basics — subscription, region, resource group (e.g. rg-insightforge).
3. Postmark Configuration — server token (required for Postmark); account token and webhook secret (optional).
4. Azure Communication Services (optional) — ACS resource ARM ID. When provided, the template creates an Event Grid subscription to acsIngestUrl and grants the InsightForge Api managed identity EventGrid EventSubscription Contributor on that ACS resource automatically.
5. Release packages — confirm zip URLs for ingest, processing, api, dashboard, and janitor.
6. Review + create → wait approximately 5–10 minutes.

The template provisions:

• Storage account — queues, tables, Flex deployment containers.
• Key Vault — Postmark tokens, storage connection string, webhook secret (RBAC).
• Four Flex Consumption Function Apps (.NET 10 isolated via functionAppConfig):
  • Ingestor — POST /api/webhooks/postmark, POST /api/webhooks/acs
  • Processing — queue worker + optional SignalR broadcast
  • Api — dashboard and setup REST APIs
  • Janitor — nightly data retention rollup
• Static Web App — React dashboard linked to the Api app.
• Deployment scripts copy each zip to released-package.zip in dedicated blob containers (no WEBSITE_RUN_FROM_PACKAGE on Flex).

Postmark webhooks: InsightForge creates its own Postmark webhooks pointing at your ingest URL. Existing customer webhooks are not modified. If a webhook with the same ingest URL already exists for a message stream, InsightForge adopts it instead of creating a duplicate.

After Deployment

1. Note template outputs ingestUrl, acsIngestUrl, apiUrl, dashboardUrl, and setupStatusUrl.
2. Automatic bootstrap (default): the Api function reads Postmark tokens from Key Vault every 5 minutes and provisions servers — webhooks, 45-day backfill, and suppression cache.
   • GET https://<dashboard-host>/api/setup/status → isProvisioned: true when ready
   • Or open Setup in the dashboard (Postmark tab shows install status)
3. Optional: POST https://<api-host>/api/setup/bootstrap to retry immediately.
4. Open dashboardUrl and sign in with Entra when configured.
5. To add ACS after install (or a second ACS resource), use Setup → Azure (ACS) — see the ACS section below.

Connecting Azure Communication Services (ACS)

ACS email delivery and engagement events flow through Event Grid into InsightForge at acsIngestUrl (template output). There are two paths:

Path A — ACS ARM ID at Marketplace install (recommended)

No manual Azure steps. The install template creates the Event Grid subscription and RBAC on the ACS resource you specify.

Path B — Connect ACS later in Setup

Use this when ACS lives in another resource group, you skipped ACS at install, or you are adding another ACS resource.

1. Open the dashboard → Setup → tab Azure (ACS).
2. Read the Before you connect ACS panel — it shows your ingest URL and (after deploy) the InsightForge Api managed identity principal ID.
3. Grant the Api managed identity EventGrid EventSubscription Contributor on the ACS resource:
   • Portal: ACS resource → Access control (IAM) → Add role assignment → select the role → assign to the Api Function App’s system-assigned identity (Object/principal ID).
   • CLI: a subscription Owner or User Access Administrator runs:

az role assignment create \
  --assignee <api-managed-identity-principal-id> \
  --role 'EventGrid EventSubscription Contributor' \
  --scope /subscriptions/.../providers/Microsoft.Communication/communicationServices/your-acs

Find the Api principal ID: Azure Portal → InsightForge Api Function App → Identity → Object (principal) ID. The Setup wizard displays this value when available.

4. Wait 1–2 minutes for RBAC propagation.
5. Paste the full ACS ARM resource ID and a display name → Connect ACS resource.

Cross–resource group ACS: Marketplace install only auto-provisions RBAC for the ACS resource ID you enter at deploy time. ACS in a different subscription or resource group always requires Path B once per ACS resource.

Dashboard & Plans

The dashboard Connections sidebar lists Postmark servers and ACS resources with provider badges. Tabs such as Domains and Suppressions are available for Postmark; ACS connections show message and event views supported by ACS event types.

Marketplace plans (Starter / Pro) control retention, server limits, and optional archive features. Plan details appear in Setup when entitlements are configured.

Verifying the Install

• GET https://<api>/api/health → {"status":"ok","service":"InsightForge.Api"}
• GET https://<api>/api/setup/status → isProvisioned: true, serverCount ≥ 1 after Postmark bootstrap
• Postmark test webhook → HTTP 202/200 from ingest; row in storage within ~1 minute
• Setup → Postmark → webhooks listed per stream
• Setup → Azure (ACS) → connected resource shows Event Grid active after successful connect
• Dashboard shows messages and events for your server or ACS resource

Troubleshooting

ACS connect fails — insufficient permissions / Event Grid

Grant EventGrid EventSubscription Contributor on the ACS resource to the InsightForge Api Function App managed identity (not the Ingestor). Retry after 1–2 minutes. Setup shows a copyable az role assignment command when the principal ID is configured.

ACS disconnect warning — Event Grid not removed

InsightForge always deactivates ACS credentials in storage. Event Grid subscription deletion requires Azure management API access from the Api app. If the Api app lacks Azure credentials in your environment, disconnect still succeeds but Event Grid may remain until you delete it manually in Portal or re-run disconnect after fixing Api identity permissions.

Functions blade empty

Wait 2–3 minutes. Confirm released-package.zip exists in deployments-ingest, deployments-processing, deployments-api, and deployments-janitor. Restart each Function App once.

Runtime / stack errors

Use Flex Consumption (FC1). Runtime is functionAppConfig → dotnet-isolated 10.0 — do not change legacy Stack settings in the portal.

Key Vault references fail

Function App → Identity → system-assigned On. Key Vault → Access control → Key Vault Secrets User for each app.

Postmark webhooks return 401

Webhook signing secret in Key Vault must match Postmark server webhook settings.

Events not processing

Processing needs Storage Queue Data Contributor on the storage account to drain webhook-payloads.

Live dashboard off

Set SignalR__ConnectionString on Processing and Api. Optional — polling refresh still works.

Local development / ngrok

Point webhooks and Event Grid at your public HTTPS tunnel to the Ingestor port (e.g. 18071), not the dashboard port. Update ingest URL in Setup and use Update all stream webhooks for Postmark after the tunnel URL changes.

Uninstall

1. Dashboard → Setup:
   • Postmark tab → Disconnect all Postmark (removes managed webhooks and deactivates Postmark credentials).
   • Azure (ACS) tab → Disconnect on each resource or Disconnect all ACS resources (removes registrations and Event Grid when Api has Azure permissions).
2. Delete the resource group:

az group delete --name rg-insightforge --yes

Support

Email support@ageebgeesolutions.com. Include resource group, region, ingest/api host names, ACS ARM ID (if applicable), and Function App Log stream lines (UTC).