Plan your deployment

Before deploying Visual Asset Management System (VAMS), review the decisions on this page to determine the architecture, authentication method, and optional features that best fit your environment.

Deployment modes

VAMS supports three deployment modes. Your choice depends on the AWS partition, network isolation requirements, and organizational security policies.

Mode	Web distribution	Partition	VPC required	Description
Commercial	Amazon CloudFront + Amazon S3	aws	Optional	Default mode. Uses Amazon CloudFront for global edge caching and static website hosting.
GovCloud	Application Load Balancer + Amazon S3	aws-us-gov	Yes	For AWS GovCloud (US) Regions. Amazon CloudFront is not available; an Application Load Balancer (ALB) serves the web application. Supports full VPC isolation with VPC endpoints for restricted environments.
EU Sovereign Cloud	Application Load Balancer + Amazon S3	aws-eusc	Yes	For the AWS European Sovereign Cloud (Region eusc-de-east-1). Deploys with the GovCloud guardrails (app.govCloud.enabled: true): no Amazon CloudFront, no Amazon Location Service. The Region exposes two Availability Zones.

GovCloud and EU Sovereign Cloud constraints

When deploying to AWS GovCloud or the AWS European Sovereign Cloud, the following services are unavailable or restricted. Configuration validation rejects a deployment that enables any of them.

• A VPC is required. Set app.useGlobalVpc.enabled to true.
• Amazon CloudFront is not supported. Use the ALB deployment mode.
• Amazon Location Service is not supported. Disable app.useLocationService.enabled.
• AWS Deadline Cloud is not supported. Disable app.pipelines.deadlineCloudExecutionTypeEnabled.
• Amazon Cognito SAML and OIDC federation are not supported — both use the Amazon Cognito hosted UI. Disable useCognito.useSaml and useCognito.useOidc, and use the external OAuth identity provider option for federated sign-in.
• Next-generation Amazon OpenSearch Serverless collections are not supported. Set app.openSearch.useServerless.nextGen to false.
• Amazon OpenSearch Serverless is not offered at all in the AWS European Sovereign Cloud. Set app.openSearch.useServerless.enabled to false and use app.openSearch.useProvisioned there.
• Amazon Cognito advanced security (AdvancedSecurityMode) is not available. VAMS does not configure it and suppresses the corresponding check automatically, so no configuration change is needed.

For the authoritative per-field list, see Restricted-partition constraints.

Key decisions

Authentication provider

VAMS supports four authentication approaches. You must choose exactly one.

Option	Configuration	Description
Amazon Cognito (default)	authProvider.useCognito.enabled: true	VAMS creates and manages an Amazon Cognito user pool. Users receive a temporary password by email. Supports optional SAML or OIDC federation.
Amazon Cognito with SAML	authProvider.useCognito.enabled: true and useSaml: true	Amazon Cognito with federated SAML from an external identity provider (IdP). Provider details are configured in infra/config/saml-config.ts.
Amazon Cognito with OIDC	authProvider.useCognito.enabled: true and useOidc: true	Amazon Cognito with federated OpenID Connect from an external IdP (for example, Okta, Microsoft Entra ID, PingFederate). Provider details are configured in infra/config/oidc-config.ts.
External OAuth IdP	authProvider.useExternalOAuthIdp.enabled: true	Bring your own OAuth 2.0 / OpenID Connect identity provider without an Amazon Cognito user pool. Requires configuring multiple IdP endpoint URLs and client credentials, plus a custom JWT issuer and audience.

Cognito federation constraints

useSaml and useOidc are mutually exclusive, and both require useCognito.enabled to be true — they are ignored when it is false. Both use the Amazon Cognito hosted UI, which is available only in the commercial aws partition, so neither can be used in AWS GovCloud or the AWS European Sovereign Cloud. Use the external OAuth IdP option for federated sign-in there.

Web distribution

Option	When to use	Configuration
Amazon CloudFront	Commercial AWS. Provides global edge caching, AWS-managed TLS, and a generated domain URL.	useCloudFront.enabled: true
Amazon CloudFront with custom domain	Commercial AWS with organizational branding requirements. Requires an AWS Certificate Manager (ACM) certificate in us-east-1.	useCloudFront.customDomain.enabled: true
Application Load Balancer	AWS GovCloud, the AWS European Sovereign Cloud, or when CloudFront is not permitted. Requires a registered domain name and an ACM certificate in the deployment Region.	useAlb.enabled: true
API only (no web UI)	Headless deployments driven entirely through API or CLI.	Both useCloudFront.enabled: false and useAlb.enabled: false

Mutual exclusion

You cannot enable both Amazon CloudFront and ALB simultaneously. The deployment will fail validation if both are set to true.

Search capability

Amazon OpenSearch Service provides full-text search, filtering, and map-view functionality in the VAMS web interface.

Option	Configuration	Notes
OpenSearch Serverless	openSearch.useServerless.enabled: true	Fully managed, pay-per-use. No VPC required. Default for commercial deployments.
OpenSearch Provisioned	openSearch.useProvisioned.enabled: true	Dedicated cluster with configurable instance types. Requires a VPC spanning availabilityZoneCount Availability Zones (2 by default, optionally 3).
No OpenSearch	Both set to false	Search is disabled. The assets page returns all authorized assets without filtering.

Choose only one

You cannot enable both OpenSearch Serverless and OpenSearch Provisioned at the same time.

Provisioned is for advanced deployments only

Amazon OpenSearch Serverless is the recommended option for most deployments. Provisioned is intended for advanced use cases that require dedicated capacity, custom instance sizing, or features unsupported by Serverless. It can complicate stack deployments — domain configuration changes trigger blue/green updates that may exceed the AWS CloudFormation custom-resource timeout, and major-version engine upgrades can fail in place and require redeploying with OpenSearch disabled before re-enabling. See the OpenSearch configuration reference for the full caveat list.

VPC configuration

Option	Configuration	Notes
No VPC	useGlobalVpc.enabled: false	Simplest deployment. Not compatible with ALB, OpenSearch Provisioned, or container-based pipelines.
VAMS-managed VPC	useGlobalVpc.enabled: true with vpcCidrRange	VAMS creates a new VPC with isolated, private, and public subnets. Specify a CIDR range (for example, 10.1.0.0/16).
Import existing VPC	useGlobalVpc.enabled: true with optionalExternalVpcId	Import an existing VPC by ID. Requires providing isolated subnet IDs and optionally private and public subnet IDs. See Deploy the solution for the two-phase deployment process.

VPC is required for some features

Some features require a VPC and useGlobalVpc.enabled must be true when they are enabled. If any of the following are turned on while useGlobalVpc.enabled is false, deployment fails with a configuration error that lists the offending features — set useGlobalVpc.enabled to true (or disable those features): ALB deployment, OpenSearch Provisioned, or any container-based pipeline (Potree viewer, Gaussian splatting, GenAI labeling, RapidPipeline, ModelOps, Isaac Lab, 3D preview thumbnail, NVIDIA Cosmos, NVIDIA Gr00t).

Subnet sizing guidance:

Feature	IPs per subnet
ALB	Up to 8 (scales during runtime)
Container-based pipelines	~2 per active workflow execution
Lambda functions in VPC	1 per deployed function per subnet
VPC interface endpoints	1 per endpoint per subnet

A minimum of 128 IPv4 addresses per subnet is recommended.

Encryption

Option	Configuration	Notes
AWS-managed keys (default)	useKmsCmkEncryption.enabled: false	Uses default or AWS-managed encryption for Amazon S3, Amazon DynamoDB, Amazon SQS, and Amazon SNS.
Customer-managed KMS key	useKmsCmkEncryption.enabled: true	VAMS creates a customer-managed AWS KMS key and applies it to all storage resources. Optionally import an existing key with optionalExternalCmkArn.