Frontend Deployment

The app can be deployed to AWS and Azure as a static Observable Framework frontend. This is intentionally separate from cloud backend setup: public website resources serve dist/, while file/document artifacts remain in the local object directory, private S3 buckets, or private Azure Blob containers behind the coordinating API.

Use this page for both AWS and Azure frontend deployment. Provider-specific approval notes are kept here so AWS and Azure remain symmetrical in the documentation; the old Azure appendix is retained only as a historical first-deployment record.

Deployment Sequence

Use this order when bringing up a new environment:

1. Run locally with npm run dev:local.
2. Confirm the local API writes metadata to .wm-data/workspace.sqlite and file bytes to .wm-data/objects/.
3. Create application accounts for clients, businesses, departments, firms, or personal workspaces.
4. Provision AWS, Azure, or both private data backends.
5. Add provider connection manifests to the coordinating node.
6. Sync local project data to the connected backend surfaces.
7. Build and deploy the static frontend when users need browser access beyond the local workstation.

When both AWS and Azure are connected, the coordinating node syncs the provider-neutral project model across configured surfaces. The public static website bucket or container should not be treated as file or document-artifact storage.

Build

npm run build

Current Development Deployment

As of July 2, 2026, the development frontend has been published to both cloud static hosting targets:

The production user-facing hostname is the AWS CloudFront URL. Signed-in workspace traffic calls the authenticated cloud API at https://ovetov6bl8.execute-api.us-east-1.amazonaws.com; that API currently persists the workspace envelope and sync bundle to AWS. Azure replication is available but disabled. The public static website bucket/container still serve only frontend files. Private file and document-artifact storage stays in authenticated backend object stores.

Independence Contract

AWS and Azure deploy independently. The AWS script reads only AWS_* settings and uploads to an S3 static website bucket. The Azure script reads only AZURE_* settings and uploads to the Azure Storage $web container. The only shared artifact is the local dist/ directory produced by npm run build.

Do not reuse one cloud's public hosting bucket/container, DNS name, or CDN distribution for the other cloud. Keep DNS/CDN front doors separate until a deliberate traffic-management layer is introduced.

AWS Frontend

AWS deployment uses a dedicated public S3 website bucket. AWS documents S3 static website hosting for static pages and client-side scripts, and the AWS CLI s3 sync command recursively copies changed files from dist/ to S3.

export AWS_REGION=us-east-1
export AWS_PROFILE=categorise
export AWS_SITE_BUCKET=workspace.categori.se
npm run deploy:aws

AWS_SITE_BUCKET defaults to workspace.categori.se when unset. Use AWS_PROFILE=categorise for account 977060200223. Set AWS_SITE_DELETE=true only when you want the script to remove remote files that are no longer in dist/.

The script also uploads extensionless HTML aliases, for example docs/deployment.html is also published as docs/deployment, so Observable Framework's clean routes work on plain S3 website hosting. When AWS_SITE_DOMAIN or AWS_SITE_DISTRIBUTION_ID is set, deploy:aws creates a CloudFront invalidation after upload unless AWS_SITE_INVALIDATE=false.

AWS Auth Gateway

The workspace frontend uses the same application-side gateway pattern as the other categori.se apps. Unauthenticated users see a centered sign-in panel with Sign in, Register, Demo, and Recover account actions. Sign-in, registration, password recovery, and sign-out use Cognito Hosted UI with PKCE.

The shared gateway UI and actions live in src/components/auth-gateway.js. The mounted workspace routes use it from src/components/workspace-management-app.js, and the site-wide Observable head script in src/workspace-chrome.js uses the same component to guard static pages such as / and /docs/*. ?demo=1 or ?preview=1 opens the public demo route without a Cognito session.

Authenticated Cloud API

The deployed workspace API is an AWS HTTP API Gateway endpoint backed by Lambda:

The API exposes the same browser contract as local development:

• GET /api/workspace
• PUT /api/workspace
• GET /api/objects/{storage_key}/status
• PUT /api/objects/{storage_key}

The deployed Lambda writes workspace envelopes and sync bundles to AWS by default:

The session banner uses the production runtime config label AWS with detail AWS S3 + DynamoDB after the authenticated API successfully hydrates workspace state. If that API is configured but unavailable, the UI reports Cloud unavailable instead of Local fallback.

Azure replication switch

Azure reads, writes, object checks, and read repair are gated by WORKSPACE_AZURE_SYNC_ENABLED. The default is false; in that mode, the deployment does not call the Azure CLI, the Lambda does not contact Azure, and Azure credentials are removed from the Lambda environment.

To restore Azure replication later, authenticate to the desired Azure account, set the new resource names, and redeploy both API and frontend with the switch enabled:

export WORKSPACE_AZURE_SYNC_ENABLED=true
export AZURE_RESOURCE_GROUP=your-resource-group
export AZURE_STORAGE_ACCOUNT=yourstorageaccount
export AZURE_COSMOS_ACCOUNT=yourcosmosaccount
npm run deploy:cloud-api
npm run deploy:aws

Set WORKSPACE_AZURE_SYNC_ENABLED=false (or leave it unset) and rerun npm run deploy:cloud-api to return to AWS-only mode.

Public Demo Account

The Demo action opens a dedicated browser-local Workspace Demo account instead of bypassing auth with the production seed. The seed lives in cloneDemoWorkspaceSeed(), and the daily browser store and quotas live in src/lib/demo-workspace.js.

Demo behavior:

• The demo user has full UI authority inside the sandbox so visitors can inspect project, file, team, account, sharing, settings, and metadata workflows.
• Three example collaborators appear in account and team membership: Priya Shah, Omar Chen, and Sofia Rivera.
• Demo changes are saved in local browser storage for the current local date, then reset back to the seed on the next local date.
• Visitors can create at most 10 new projects per local day.
• Visitors can stage or upload at most 300 MiB of files per local day, enough for roughly a dozen large photos or similar media files.
• These limits are client-side demo guardrails, not a replacement for backend authorization or storage quotas on production APIs.

Current auth resources:

The gateway protects application routes and static documentation entry points from casual unauthenticated browsing, and keeps private workspace flows behind a Cognito session before workspace data hydration. API Gateway enforces the Cognito bearer token for cloud persistence. The static S3 website bucket remains a public origin because this deployment uses S3 website hosting; private workspace data is accessed through the authenticated API.

AWS HTTPS Custom Domain

Use setup:aws:site-domain after the S3 website bucket has been created by deploy:aws. The script creates or reports one CloudFront distribution for the requested alias, uses the S3 website endpoint as the origin, redirects HTTP viewers to HTTPS, and maps 403/404 responses back to index.html for clean Observable routes.

For the current workspace.categori.se deployment:

export AWS_REGION=us-east-1
export AWS_PROFILE=categorise
export AWS_SITE_BUCKET=workspace.categori.se
export AWS_SITE_DOMAIN=workspace.categori.se
export AWS_SITE_CERTIFICATE_ARN=arn:aws:acm:us-east-1:977060200223:certificate/79ce96a2-6b18-48ac-b334-abdc0a5dc25d
npm run deploy:aws
npm run setup:aws:site-domain

The active target-account CloudFront distribution is:

Because categori.se is not hosted in Route53 in this AWS account, manage DNS in DNSMadeEasy or the active DNS provider. The production DNS record should point the subdomain to CloudFront:

workspace CNAME d28y8aivxdwrn7.cloudfront.net

Keep this ACM validation record in place so the certificate can renew automatically:

_bdede6a9b74260a9787d5e37958bf04e.workspace CNAME _9343714ced34b51e35ddc54df1b60b24.jkddzztszm.acm-validations.aws.

Current DNS and certificate findings:

• categori.se is delegated to DNSMadeEasy name servers.
• Account 977060200223 hosts the workspace.categori.se S3 website bucket.
• Account 977060200223 has an issued us-east-1 ACM certificate for workspace.categori.se.
• No Route53 hosted zone for categori.se is visible in this AWS account.
• workspace.categori.se should have an explicit DNSMadeEasy CNAME to d28y8aivxdwrn7.cloudfront.net so it does not fall through to an unrelated wildcard route.
• catgori.se did not return delegated name servers during the July 2, 2026 deployment check, and no matching ACM certificate was found.

If the intended hostname is exactly workspace.catgori.se, request and validate a separate us-east-1 ACM certificate and create DNS validation records in the authoritative DNS provider before running setup:aws:site-domain.

AWS Approval Notes

Ask IT to approve or provide:

• A dedicated public S3 static website bucket for the target environment.
• A named deployment identity, such as a user, CI role, or assumed role, with write access only to that frontend bucket.
• Permission for the deployment script to configure website hosting, bucket policy, and public-read behavior for generated static files.
• Confirmation that no private project files, document artifacts, credentials, .wm-data files, or backend secrets are published to the frontend bucket.
• A DNS and HTTPS decision. Plain S3 website endpoints do not provide custom-domain HTTPS by themselves; this repo uses CloudFront for the scripted AWS custom-domain path.

The AWS frontend bucket is separate from the private S3 document bucket created by npm run setup:aws.

Azure Frontend

Azure deployment uses a dedicated StorageV2 account with static website hosting enabled and uploads dist/ into the $web container.

az login
az account set --subscription "<subscription-id-or-name>"

export AZURE_RESOURCE_GROUP=wm-site-rg
export AZURE_LOCATION=eastus
export AZURE_SITE_STORAGE_ACCOUNT=<globally-unique-lowercase-name>
npm run deploy:azure

The script defaults Blob uploads to AZURE_STORAGE_AUTH_MODE=key, which lets the deployment account use the storage account key immediately after creating the account. Set AZURE_STORAGE_AUTH_MODE=login only after assigning the deploying identity a Blob Data role on the storage account. Set AZURE_SITE_DELETE=true only when you want the script to clear $web before uploading.

The script also uploads extensionless HTML aliases, for example docs/deployment.html is also published as docs/deployment, so Observable Framework's clean routes work on Azure Storage static website hosting.

Azure Approval Notes

Ask IT to approve or provide:

• Registration of the Microsoft.Storage resource provider on the subscription, if it is not already registered.
• A dedicated resource group and StorageV2 account for the public static frontend.
• Static website hosting enabled with index.html as both the index and error document.
• A named deployment identity with Storage Blob Data Contributor scoped to the storage account or $web container when using AZURE_STORAGE_AUTH_MODE=login.
• A key policy decision. If shared keys are disallowed, use AZURE_STORAGE_AUTH_MODE=login after RBAC propagates.
• Confirmation that Azure Storage static website content is anonymous read-only from $web; it is not private Entra-authenticated hosting by itself.
• A DNS and HTTPS decision. Custom-domain HTTPS should usually be reviewed through Azure Front Door or Azure CDN.

The Azure frontend $web container is separate from the private Blob container created by npm run setup:azure. The first Azure deployment record is retained in Azure Backend Setup.

Deployment Approval Summary

Use this summary when requesting approval for either cloud.

Backend Baselines

Use these when you also want to create the private data resources:

npm run setup:aws
npm run setup:azure

The setup scripts create baseline private object storage and metadata databases. They do not deploy API compute, custom domains, HTTPS CDN fronts, identity callback apps, or email sender verification.

Internal Corporate Deployment

When the corporation already has cloud storage, ask IT to provide or approve a dedicated static-site storage target and a separate private file/artifact storage target.

For the frontend static site, request:

• A dedicated AWS S3 website bucket or Azure Storage static website account for the development environment.
• A named deployment identity, such as a user, service principal, or CI role, with write access only to that static website bucket/container.
• Permission to publish generated dist/ files and extensionless HTML route aliases.
• Confirmation that static website content is public unless placed behind CloudFront, Azure Front Door, a reverse proxy, VPN, or another corporate access-control layer.
• DNS and HTTPS ownership decision: S3 website endpoints need CloudFront for HTTPS/custom domains; Azure Storage static websites normally need Azure Front Door or Azure CDN for custom-domain HTTPS.

For private project data, request:

• A separate private object/blob container for raw files and derived artifacts.
• Data-plane write/read permissions only for the backend API or worker identity, not for anonymous static website users.
• Encryption, lifecycle retention, logging, and backup settings that match corporate data classification.
• A metadata store, such as DynamoDB or Cosmos DB, with access restricted to the backend API identity.
• A secrets location, such as AWS Secrets Manager or Azure Key Vault, for API credentials and integration secrets.

Do not use the public static website bucket/container for private files or document artifacts.

Command Separation Audit

The deployment scripts are intentionally independent.

The only shared step is the local static build:

npm run build

After that, AWS uploads to S3 and Azure uploads to the $web container. Neither deployment script calls the other cloud CLI, reads the other cloud's environment variables, or writes to the other cloud's public hosting resource.

The backend baseline scripts are also separate:

Production Notes

For AWS production hosting, prefer an approved HTTPS front door such as CloudFront or Amplify Hosting in front of S3 for CDN behavior and custom-domain TLS.

For Azure production hosting, use Azure Front Door or Azure CDN when you need custom-domain HTTPS, caching rules, and edge routing in front of the static website endpoint.

References

• AWS: Hosting a static website using Amazon S3
• AWS CLI: aws s3 sync
• Azure: Static website hosting in Azure Storage
• Azure CLI: az storage blob upload-batch