Support/Partners & MSPs/Deploy the SaaS asset domain and storage root
/

Partners & MSPs

Deploy the SaaS asset domain and storage root

Configure persistent asset storage and route assets.buildwithhq.com to the tenant runtime without exposing database or filesystem authority.

Public host
assets.buildwithhq.com
Storage
Operator selected
Proxy rule
Preserve Host
Docker
Not required

The tenant runtime stores SaaS files beneath one operator-controlled root and serves explicitly public design assets through assets.buildwithhq.com. Builders may choose virtual folders inside their SaaS, but only an appliance operator can select or change the physical storage location.

1. Choose persistent storage

  1. Create a dedicated persistent directory on the appliance volume. Do not use a temporary deployment, build-output, user-profile, or source-tree directory.
  2. Grant the tenant-runtime operating-system identity read, create, and delete access only to that directory.
  3. Set BWHQ_FILE_STORAGE_ROOT for the tenant-runtime process before it starts.
  4. Include the directory in the appliance backup, restore, capacity, and integrity-monitoring plan.
HostExample value
Linux appliance guest/var/lib/buildwithhq/files
Windows service hostD:\BuildWithHQData\Files
Important

Changing BWHQ_FILE_STORAGE_ROOT does not move existing bytes. Stop uploads, copy and verify the complete existing tree while preserving relative keys, change the setting, then verify old private and public assets before reopening writes.

2. Configure the asset host

Set the ASP.NET Core configuration key Assets:PublicHost, normally through environment variable Assets__PublicHost=assets.buildwithhq.com. The public controller returns 404 on a different Host value, so the reverse proxy must preserve the original request host.

  1. Create DNS for assets.buildwithhq.com pointing at the approved public edge or load balancer.
  2. Issue and renew a valid TLS certificate for that exact hostname.
  3. Route HTTPS requests for that host to the tenant-runtime service.
  4. Preserve Host: assets.buildwithhq.com; do not rewrite it to the internal service name.
  5. Do not expose SQL Server, storage paths, management endpoints, or a directory-listing handler on the asset virtual host.
Note

The application generates public URLs with the fixed production origin https://assets.buildwithhq.com. Assets__PublicHost is a request-host validation setting, not a second public URL generator.

3. Understand the route and database boundary

A request has only /{saasAppId}/{assetId}. The server resolves an active SaaS identity through the Customers control-plane contract, creates a server-owned routed tenant connection, and retrieves metadata only when the asset is explicitly public and active. Storage provider and relative storage key stay inside the service.

API users and browsers receive no SQL credential, table permission, filesystem permission, server path, or database name. Runtime SQL principals retain allow-listed stored-procedure execution only; they do not receive DDL authority.

4. Browser delivery policy

  • Validated CSS and reviewed passive image, video, font, and PDF MIME types may render inline.
  • Other accepted files are returned as application/octet-stream attachments with X-Content-Type-Options: nosniff and a sandbox content-security policy.
  • Public responses allow cross-origin asset use and use a one-year immutable cache because the URL is identity-versioned.
  • DLL, COM, and EXE extensions are rejected before storage. Filename normalization also blocks case and trailing-dot variants.

5. Verify the deployment

  1. Start the tenant runtime with both settings present.
  2. In a disposable SaaS, upload a small public PNG in App Assets and copy its returned URL.
  3. Request the URL from outside the appliance network and confirm HTTP 200, TLS trust, Access-Control-Allow-Origin: *, X-Content-Type-Options: nosniff, and immutable cache control.
  4. Upload a private asset and confirm its authenticated /api/assets/.../content route works while no public asset-domain URL is issued.
  5. Remove the disposable public asset and confirm the old URL returns 404.
  6. Request the same path using the wrong Host header and confirm it returns 404.
Important

Do not call the deployment complete from a loopback-only test. DNS, certificate trust, preserved Host routing, public reachability, and a route-resolved disposable SaaS must all be exercised.

6. Operations checklist

  • Monitor storage capacity, write failures, public 404/5xx rates, and certificate expiry.
  • Back up asset bytes with the corresponding tenant databases and retain restore evidence.
  • Keep directory browsing disabled and storage inaccessible from the public web server except through the asset controller.
  • Use a controlled migration procedure before changing the root.
  • Remember that current template installation does not yet copy/remap asset bytes into a destination SaaS.

Builders should continue with Host SaaS CSS, logos, images, and design assets.

Capability review: 2026-09-14. For exact current technical availability, use the generated API Map and first-class module inventory.