Heritage Docs

Appearance

0026 — Production Domain and DNS Strategy ​

Status: Accepted (2026-06-21) — amended by ADR 0028

Date: 2026-06-21

ADO work item: AB#3675

Deciders: Kristopher Turner (platform owner)

Context ​

The platform needs a stable, publicly reachable production domain before any user-facing deployment can proceed. Three candidate names are available: heritageva.app, heritageva.net, and heritageva.org.

DNS management for HCS infrastructure already runs through Cloudflare. Email forwarding from the domain to kris@hybridsolutions.cloud is live via Cloudflare Email Routing — no MX infrastructure needs to be provisioned or maintained.

The stack in play at deploy time (from ADRs 0004 and 0024):

  • Web app (apps/web) — Azure Static Web Apps (SWA) Free tier; installable PWA; opens to sign-in/register (no public/marketing site).
  • API (apps/api) — containerized Node.js on Azure Container Apps; exposes a REST + WebSocket API.
  • SSL/TLS — Azure provides managed certificates for both SWA custom domains and Container Apps managed certs; no external certificate authority is required.

The three TLD options differ in one operationally significant way: the .app TLD is HSTS-preloaded in all major browsers. Any domain under .app is required to serve HTTPS — browsers will refuse an HTTP connection to a .app domain before any server response. This aligns with the platform's security posture and removes the need for an explicit HTTP-to-HTTPS redirect at the application or infrastructure layer.

Decision ​

The production domain is heritageva.app. DNS is managed in Cloudflare under the existing HCS account. Azure-managed certificates handle TLS for all subdomains. Email is forwarding-only via Cloudflare Email Routing — no MX infrastructure is provisioned.

Domain selection ​

CandidateNotesDecision
heritageva.appHSTS preloaded; HTTPS enforced by TLD; clean and directChosen
heritageva.netGeneric TLD; HTTP redirect to HTTPS must be managed explicitlyNot chosen
heritageva.orgCommon for nonprofits; same drawback as .net on HTTPS enforcementNot chosen

The .app TLD's HSTS preload is the deciding factor: HTTPS is enforced at the browser level with no redirect logic required in the application stack or infrastructure.

DNS records (created at deploy time) ​

TypeNameValuePurpose
CNAME@SWA default hostname (e.g. heritageva-swa-prod.azurestaticapps.net)Web app root domain
CNAMEapiContainer App FQDNAPI subdomain
TXT@SWA domain validation tokenSWA managed certificate validation
TXTasuid.apiContainer App domain validation tokenContainer Apps managed certificate validation

Cloudflare proxy (orange-cloud) status for each record is evaluated at deploy time against Azure's certificate validation requirements; some managed certificate flows require DNS-only (grey-cloud) during initial provisioning.

SSL/TLS ​

  • Apex (heritageva.app) — Azure SWA built-in managed certificate; issued and renewed automatically once the CNAME and TXT validation records are in place.
  • Portal subdomains (*.heritageva.app) — Cloudflare Universal SSL (free, covers apex and first-level wildcard). Cloudflare proxies all portal subdomains to the SWA default hostname via an Origin Rule. Azure-managed certs are not used for subdomains — see ADR 0028 for the full decision and rejected alternatives.
  • API — Azure Container Apps managed certificate; same validation flow via the asuid.api TXT record.
  • No external certificate authority, no manual renewal, no certificate storage in Key Vault.

Email ​

Cloudflare Email Routing is already configured to forward mail addressed to the domain to kris@hybridsolutions.cloud. No MX records pointing to an SMTP infrastructure are required. This configuration is out of scope for deploy-time DNS work; it is already live.

HTTP ​

No HTTP listener is configured at the application or infrastructure layer. The .app TLD HSTS preload makes browser-initiated HTTP connections fail before any server response, so an HTTP-to-HTTPS redirect would never be reached. Azure SWA and Container Apps are configured to serve HTTPS only.

Alternatives considered ​

OptionProsConsWhy not chosen
heritageva.app — HSTS preloaded .app TLD (chosen)HTTPS enforced by TLD; no redirect infrastructure; clean nameSlightly less familiar TLD to some users— chosen
heritageva.orgRecognized nonprofit TLD; broadly familiarRequires explicit HTTPS enforcement at app/infra layer; one more config surfaceThe .app enforcement is simpler and more reliable
heritageva.netGeneric; widely understoodSame HTTPS enforcement gap as .org; no meaningful advantage over .orgNot chosen for same reasons as .org; .app preferred
External DNS provider (Azure DNS, Route 53)May simplify Azure-native integration for cert validationCloudflare is already in use for HCS; migrating DNS for one domain adds operational complexity with no benefitNot chosen — keep DNS in existing Cloudflare account
Self-managed TLS certificates (Let's Encrypt, ACM-style)Full control over cert lifecycleAdds renewal automation, storage in Key Vault, and operational burdenNot chosen — Azure-managed certs cover both SWA and Container Apps at no cost with automatic renewal

Consequences ​

Positive ​

  • HTTPS-only by TLD enforcement; no redirect logic, no misconfiguration risk at the HTTP layer.
  • DNS centralized in the existing Cloudflare account alongside other HCS infrastructure; no new DNS provider account or tooling.
  • Azure-managed certificates for both the web app and API eliminate cert rotation as an operational concern.
  • Email forwarding is already live; no mail infrastructure to provision at deploy time.
  • Clear, memorable domain name consistent with the platform's identity.

Negative / trade-offs ​

  • The .app TLD is less conventional than .org for a ministry context; some members may find .org more familiar. Judged acceptable given the security benefit.
  • Cloudflare proxy (orange-cloud) may need to be toggled to DNS-only during Azure managed certificate initial validation, then re-enabled after issuance. This is a minor deploy-time procedural step, not an ongoing concern.

Risks ​

  • Certificate validation timing — Azure managed certificate issuance can take up to 24 hours and requires DNS propagation to complete first. Mitigation: add DNS records well before launch date; verify propagation with dig or similar before triggering certificate provisioning.
  • Cloudflare proxy interference — Cloudflare's orange-cloud proxy can intercept Azure's HTTP challenge during cert validation. Mitigation: switch to DNS-only (grey-cloud) for the relevant CNAME during provisioning; switch back after the certificate is issued.
  • Domain registration lapse — if the heritageva.app registration expires, the domain becomes available to anyone. Mitigation: enable auto-renewal in the registrar; confirm the registrar account contact email is a monitored address.

References ​

Heritage Community Hub — Internal. Access restricted via Cloudflare Access + Entra ID.

Heritage Virginia · Owner: Kristopher Turner