nexu-io__open-design/deploy/aws/README.md

OpenDesign AWS Deployment

This directory contains an AWS CloudFormation template (template.yaml) to deploy OpenDesign into your AWS environment using Amazon Elastic Container Service (ECS) with AWS Fargate.

Architecture Overview

The template provisions a robust, fault-tolerant, and secure architecture for OpenDesign:

• Networking: A new Virtual Private Cloud (VPC) spanning two Availability Zones, with both Public and Private subnets. Two independent NAT Gateways (one in each AZ) provide highly available outbound internet access.
• Load Balancing: An internet-facing Application Load Balancer (ALB) routes incoming traffic. It optionally supports HTTPS if a custom domain and ACM certificate are provided.
• Compute: AWS ECS running on serverless Fargate instances in the private subnets. To protect the file-based SQLite database from concurrent network write corruption, the service hard-codes a single-instance baseline (DesiredCount: 1). However, it leverages the multi-AZ networking primitives for Active-Passive fault tolerance: if a task or zone fails, ECS automatically reschedules the container in the healthy AZ. The task definition includes:
  • The OpenDesign app container.
  • An Nginx Auth Proxy sidecar container that securely attaches the OpenDesign API Token to incoming /api/ requests.
• Storage: Amazon Elastic File System (EFS) is mounted to the Fargate containers for persistent daemon storage. Before documenting or changing the mount, you MUST read root AGENTS.md → Daemon data directory contract. This README MUST NOT restate it. EFS is configured with deletion protection (Retain) to prevent accidental data loss.
• Security:
  • Secrets Manager: Securely stores the OpenDesign API Token, preventing it from being exposed in plain text.
  • Security Groups: Restrict traffic flow. The ALB requires an explicitly configured CIDR — ensure this is your VPN or corporate range to avoid unintended public exposure. Fargate only accepts traffic from the ALB; EFS only accepts traffic from Fargate.
• Logging: Amazon CloudWatch Log Group captures container logs for easy debugging.

Prerequisites

• An AWS Account.
• AWS CLI installed and configured with appropriate permissions.
• (Optional) An ACM Certificate ARN if you want to use a custom domain with HTTPS.

Parameters

When deploying the CloudFormation stack, you can customize the following parameters:

Parameter	Description	Default
AllowedSourceIp	(Required) The specific IPv4 CIDR block allowlisted to access the Load Balancer. The ALB requires an explicitly configured CIDR — ensure this is your VPN or corporate range to avoid unintended public exposure. Accepts any valid IPv4 range with a subnet mask between /16 and /32.	None
ApiToken	(Required) The secure API token used to authenticate requests to the OpenDesign backend. It is stored securely in AWS Secrets Manager.
DockerImage	(Required) The full repository URI and tag for the OpenDesign Docker image. You must provide an explicit image as the public Docker Hub baseline is currently unmaintained.	None
VpcCidr	The CIDR block for the VPC.	10.42.0.0/16
PublicSubnet1Cidr	The CIDR block for Public Subnet 1 (AZ1).	10.42.1.0/24
PublicSubnet2Cidr	The CIDR block for Public Subnet 2 (AZ2).	10.42.3.0/24
PrivateSubnet1Cidr	The CIDR block for Private Subnet 1 (AZ1).	10.42.2.0/24
PrivateSubnet2Cidr	The CIDR block for Private Subnet 2 (AZ2).	10.42.4.0/24
TaskSize	The compute size for the OpenDesign application. Allowed values: small (256 CPU, 1024 MiB), medium (512 CPU, 2048 MiB), large (1024 CPU, 4096 MiB).	small
TaskCpuArchitecture	The CPU architecture for the ECS task. Must match the architecture of your Docker image. Allowed values (available as a dropdown): X86_64, ARM64.	X86_64
CustomDomainName	(Optional) Your custom domain name (e.g., design.yourcompany.com). If provided, you must manually create a DNS CNAME/Alias record pointing to the ALB after deployment. If blank, the default ALB DNS name is used over HTTP.	None
AcmCertificateArn	(Optional) The ARN of your AWS Certificate Manager (ACM) certificate. Required if CustomDomainName is provided.	None
ProxyPort	The dynamic port used by the Nginx proxy and exposed to the Load Balancer. Must be >= 1024 (unprivileged container).	8080
AppStoragePath	Persistent daemon storage path. Before setting or documenting it, you MUST read root AGENTS.md → Daemon data directory contract.	See root contract

Deployment

You can deploy this stack via the AWS Management Console or the AWS CLI.

Using AWS Management Console

1. Log in to the AWS Management Console and navigate to the CloudFormation service.
2. Click Create stack and select With new resources (standard).
3. Under Prerequisite - Prepare template, select Template is ready.
4. Under Specify template, select Upload a template file, click Choose file, and select the template.yaml file from this directory.
5. Click Next.
6. Enter a Stack name (e.g., open-design-stack).
7. Fill in the Parameters according to your requirements. Note that ApiToken, AllowedSourceIp, and DockerImage are required.
8. Click Next. Configure any stack options if desired, then click Next again.
9. Scroll to the bottom of the review page, check the box that says I acknowledge that AWS CloudFormation might create IAM resources, and click Submit.

Using AWS CLI

1. Open your terminal and navigate to this directory.
2. Run the aws cloudformation deploy command, passing in the required parameters (ApiToken, AllowedSourceIp, and DockerImage):

aws cloudformation deploy \
  --template-file template.yaml \
  --stack-name open-design-stack \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides \
    ApiToken="YOUR_SECURE_API_TOKEN" \
    AllowedSourceIp="YOUR_IP_ADDRESS/32" \
    DockerImage="your-registry/open-design:latest"

Note: If you want to use a custom domain with HTTPS, include the CustomDomainName and AcmCertificateArn parameters in the --parameter-overrides list.

Accessing the Application

Once the CloudFormation stack creation is complete, go to the Outputs tab of the stack in the AWS CloudFormation Console to find the AlbDnsName and AppUrl.

If you did NOT use a custom domain: Access OpenDesign directly using the HTTP URL provided in AppUrl.

If you used a Custom Domain (HTTPS): You must create a DNS record to route traffic to your new load balancer. Go to your DNS provider (e.g., AWS Route53, Cloudflare) and create a CNAME or Alias (A) record that points your CustomDomainName to the AlbDnsName output value. Once DNS propagates, you can access OpenDesign securely via your custom HTTPS domain.