Deploying AlertD to AWS

This guide walks you through deploying AlertD to your AWS account using CloudFormation. The deployment creates a fully managed, containerized application running on ECS Fargate, served to your users over HTTPS through an Amazon CloudFront distribution.

aws iam create-service-linked-role --aws-service-name ecs.amazonaws.com

Step 0: Subscribe to AlertD on AWS Marketplace

AlertD is available on the AWS Marketplace.

AlertD is publicly available — any AWS account can subscribe, with a free 30-day trial and no contract.

Subscribe to AlertD

1. Visit the AWS Marketplace listing: AWS Marketplace - AlertD 
2. Click View purchase options
3. Review the offer and usage-based pricing, then submit the subscription
4. Wait for the confirmation page. AWS shows “Your request is in progress, this will take a few minutes. Don’t refresh or close this page.” — leave the tab open until it completes
5. When the page confirms your agreement is Active, your subscription is ready

Once subscribed, proceed with the CloudFormation deployment below.

Step 1: Open CloudFormation Console

1. Sign in to your AWS Management Console
2. Navigate to CloudFormation → Stacks
3. Ensure you’re in the correct AWS region where you want to deploy AlertD (see supported regions)
4. Verify the Stacks view is displayed

Step 2: Create a New Stack

1. Click Create stack
2. In the dropdown, select With new resources (standard)
3. This will initiate a new CloudFormation stack deployment

Step 3: Specify the AlertD Template

1. Under Prerequisite – Prepare template, select Choose an existing template
2. Under Specify template, select Amazon S3 URL
3. Paste the AlertD CloudFormation template URL:

https://alertd-publicassets.s3.us-west-1.amazonaws.com/cloudformation/AlertD_PAYG.yml

4. Click Next to proceed to stack configuration

Step 4: Configure Stack Name and Domain

Stack Name

Enter a descriptive stack name:

alertd

The stack name prefixes the names of the resources AlertD creates (for example alertd-aurora-cluster), so keep it short.

Domain & Certificate Configuration (Optional)

AlertD is served through Amazon CloudFront. If you leave both fields blank, CloudFront gives your deployment a working HTTPS URL on its default *.cloudfront.net domain — no domain or certificate needed. This is the quickest way to get started.

To serve AlertD from your own domain instead, fill in both fields:

• Custom Domain Name (DomainName): the host name users will visit, for example alertd.example.com
• Certificate ARN (us-east-1) (CertificateArn): the ARN of an ACM certificate that covers that host name

• The certificate must be issued (validated) and trusted — CloudFront does not accept self-signed certificates
• If you provide a Custom Domain Name without a Certificate ARN, CloudFormation rejects the stack before creating anything
• You can leave both blank now and add a custom domain later with a stack update (see Step 16)
• See the prerequisites guide for how to request a certificate

Step 5: Configure Version and Aurora Capacity

• AlertD Application Version (Version): the AlertD release to run. It defaults to the release the template was published with — leave it unchanged.
• Minimum Aurora Capacity Units (ACU) (AuroraMinCapacity): default 2
• Maximum Aurora Capacity Units (ACU) (AuroraMaxCapacity): default 16

Aurora Serverless v2 scales between these two values. The defaults suit most environments.

Step 6: Configure Model API Keys (Optional)

By default AlertD uses Amazon Bedrock, which needs no API key — leave this whole section blank to use it. Bedrock inference is billed on your AWS bill.

The Model Configuration section holds optional credentials if you want AlertD to use an external LLM provider instead:

• OpenAI API Key — your OpenAI key
• OpenAI Endpoint — an OpenAI-compatible API endpoint URL, if you use one instead of OpenAI’s default
• Anthropic API Key — your Anthropic API key
• Gemini API Key — your Google Gemini API key

Leave any field blank that you don’t need. If all key fields are blank, AlertD uses Bedrock.

Step 7: Configure Monitoring Role

Create Monitoring Role

This parameter controls whether CloudFormation automatically creates the IAM role that AlertD uses to monitor your AWS infrastructure.

• true (default) — Automatically creates an IAM role with ReadOnlyAccess and the correct trust policy. Use this if AlertD will monitor the same AWS account it is deployed in. No manual IAM configuration is needed — proceed to Simple Setup after deployment.

• false — Does not create a monitoring role. Use this if AlertD will monitor a different AWS account. You will need to manually create the IAM role in the target account during Advanced Setup.

Step 8: Configure Data Retention

Stack Delete Policy

StackDeletePolicy decides what survives if you ever delete the stack:

• Snapshot DB and Delete bucket (default) — takes a final Aurora snapshot, then deletes everything else
• Retain DB and Bucket — keeps the Aurora cluster, the storage bucket and the VPC, so you can delete the stack and later relaunch it against the same data by importing those resources

You can change this later with a stack update; the change doesn’t touch any running resource.

Step 9: Configure Networking

AlertD can deploy in a new VPC or use your existing network infrastructure. In both cases the load balancer is internal — CloudFront reaches it privately through a CloudFront VPC origin, so nothing in your VPC is exposed to the internet.

Option A: New VPC (Default)

Leave both fields blank, and CloudFormation will automatically create:

• New VPC with public and private subnets across 2 availability zones
• NAT Gateway for private subnet internet access
• Security groups and routing tables

Option B: Existing VPC

If deploying into an existing VPC, provide:

1. VPC ID: Your existing VPC identifier (e.g., vpc-0123456789abcdef0)
2. Private Subnet IDs: Comma-separated list of private subnet IDs for the ECS tasks and the internal load balancer
   • Example: subnet-abc123,subnet-def456
   • Must have outbound internet access via NAT Gateway

No public subnets are needed.

Step 10: Configure Auto-Update

The last three parameters control AlertD’s auto-update mechanism, a small Lambda function that runs on a schedule in your account:

Click Next to continue.

Step 11: Configure Stack Options

On the Configure stack options page:

1. (Optional) Add tags to help identify your resources
   • Example: Environment: Production, Team: DevOps
2. (Optional) Assign an IAM Role for CloudFormation
   • Leave blank to use your current credentials
3. Keep rollback, notification, and timeout settings as default
4. (Recommended) Under Stack creation options, activate Termination protection so the stack can’t be deleted by accident

Scroll down to the capabilities section.

Step 12: Acknowledge IAM Resource Creation

CloudFormation needs permission to create IAM roles and resources for AlertD.

1. Locate the Capabilities section at the bottom of the page
2. Check the box that states:

☑ I acknowledge that AWS CloudFormation might create IAM resources with custom names.

3. This acknowledgment is required because AlertD creates:
   • The ECS task execution role and the AlertD task role
   • The read-only monitoring role (if CreateMonitoringRole is true)
   • Roles for the Lambda functions that support deployment and auto-update

Click Next to proceed to the review page.

Step 13: Review and Submit

The Review and create page displays a summary of all your configuration:

Review These Critical Settings:

• Template URL: Verify it points to the AlertD CloudFormation template
• Stack Name: Confirm stack name is correct
• Custom Domain Name and Certificate ARN: Both blank, or both set with a us-east-1 certificate
• Model Configuration: Verify any API keys you entered
• Networking Configuration: Confirm VPC and subnet settings
• Termination protection: Activated, if you chose to

Submit the Stack

1. Carefully review all parameters
2. If everything looks correct, click Submit at the bottom of the page
3. CloudFormation will begin creating your AlertD infrastructure

Step 14: Monitor Stack Creation

After submission, CloudFormation begins provisioning resources:

1. The stack status will show CREATE_IN_PROGRESS
2. You can monitor progress in the Events tab
3. CloudFormation creates, roughly in this order:
   • VPC, subnets, and networking components (if new VPC)
   • Security groups
   • Aurora Serverless v2 (PostgreSQL-compatible) cluster
   • S3 storage bucket
   • ECS cluster and task definitions
   • Internal load balancer and target group
   • ECS services
   • CloudFront VPC origin and distribution
   • Auto-update function (if enabled)

Expected duration: 10-15 minutes

Step 15: Verify Stack Completion

When deployment finishes:

1. The stack status updates to CREATE_COMPLETE (green checkmark)
2. Click the Outputs tab
3. Record the following important values:

Critical Outputs

AlertDApplicationURL

• The public URL for accessing your AlertD web application
• Format: https://d1234abcd.cloudfront.net, or https://<your custom domain> if you set one
• You’ll use this URL to access AlertD and complete setup

CloudFrontDomainName

• The CloudFront distribution’s domain name, for example d1234abcd.cloudfront.net
• Point your custom domain’s DNS record here (see Step 16)

Other Outputs

Step 16: Configure a Custom Domain (Optional)

Skip this step if you’re using the default *.cloudfront.net URL.

If you set Custom Domain Name and Certificate ARN in Step 4, point that domain at CloudFront.

Create a DNS Record

In your DNS provider (e.g., Route 53, Cloudflare), create a CNAME record:

Type: CNAME
Name: alertd.example.com
Value: <CloudFrontDomainName from CloudFormation Outputs>

Example:

alertd.example.com → d1234abcd.cloudfront.net

In Route 53 you can use an Alias record pointing to the CloudFront distribution instead of a CNAME.

Verify SSL Certificate

• Ensure your ACM certificate in us-east-1 covers the custom domain you’re using
• The certificate should be validated before DNS propagation completes
• DNS changes typically propagate within 5-60 minutes

Adding a Custom Domain Later

If you deployed without a custom domain, choose Update stack → Use existing template, set Custom Domain Name and Certificate ARN (us-east-1), and submit. When the update completes, create the DNS record above.

Step 17: Verify the Deployment

Before handing AlertD to your team, run through this short smoke test to confirm the stack is healthy and the application is serving traffic. The whole check takes 2–3 minutes.

1. Confirm the Stack Status

In CloudFormation → Stacks, the AlertD stack must be in state CREATE_COMPLETE with no failed events on the Events tab.

2. Confirm the ECS Services Are Stable

In ECS → Clusters → <AlertD cluster> → Services, each service should show:

• Running tasks equal to Desired tasks
• Deployment rollout status COMPLETED
• No tasks in Stopped state with recent timestamps

3. Confirm the Load Balancer Target Group Is Healthy

In EC2 → Load Balancers → Target groups, the application target group should show every registered target with Health status = healthy. An unhealthy target indicates the application is not responding to the load balancer’s health check.

4. Confirm the Application Started Cleanly

Tail the application log stream and look for the startup banner with no ERROR or stack-trace lines:

aws logs tail /ecs/<stack-name>/app --since 10m

If you see repeated errors or a crash loop, check the first lines of the newest log stream for the startup failure.

5. Open the Application in a Browser

Visit your AlertDApplicationURL in a browser. You should see the Welcome to AlertD → Authentication Setup screen, served over HTTPS with a valid certificate.

If all five checks pass, the deployment is verified. Proceed to either the Simple Setup or Advanced Setup to complete the application-level configuration.

✅ Deployment Complete!

Your AlertD infrastructure is now running in your AWS environment. The application consists of:

• Amazon CloudFront distribution terminating HTTPS for your users
• Internal Application Load Balancer, reachable only from CloudFront through a VPC origin
• ECS Fargate Cluster running the AlertD app and Pulsar services
• Aurora Serverless v2 (PostgreSQL-compatible) cluster as the primary data store
• Amazon S3 bucket for application storage and logs
• Private Service Discovery for internal service communication
• CloudWatch Logs capturing application logs
• Secrets Manager storing database credentials and API keys securely
• Auto-update Lambda function (if EnableAutoUpdate is true)

Resources Created

The CloudFormation stack creates resources including:

• VPC with public/private subnets (if new VPC option selected)
• NAT Gateway and Internet Gateway (if new VPC option selected)
• Security groups for each service, with the load balancer accepting traffic only from CloudFront
• ECS task definitions and services
• Internal Application Load Balancer with listener and target group
• CloudFront VPC origin and distribution
• S3 bucket and file system for application storage
• CloudWatch log groups
• Service discovery namespace
• Lambda functions for deployment helpers and auto-update

Next Steps

Now that AlertD is deployed, you need to complete the initial setup. Choose the path that matches your deployment:

• Same-account monitoring (CreateMonitoringRole = true, the default): The IAM role was created automatically. Proceed to the simple setup to authenticate and start using AlertD.

  Continue to Simple Setup →

• Cross-account monitoring (CreateMonitoringRole = false): You need to manually create an IAM role in the target account. Proceed to the advanced setup.

  Continue to Advanced Setup →

Troubleshooting

Stack Creation Failed

If your stack fails to create:

1. Check the Events tab for error messages
2. Common issues:
   • ECS service-linked role missing (see below)
   • Custom Domain Name provided without a Certificate ARN, or the certificate isn’t in us-east-1
   • Region doesn’t support CloudFront VPC origins (the stack fails immediately with “This Region does not support CloudFront VPC origins”)
   • Existing-VPC subnets in an availability zone that doesn’t support CloudFront VPC origins
   • Insufficient IAM permissions for the deploying user
   • VPC subnet configuration errors (if using existing VPC)

ECS Cluster Fails with “Unable to Assume the Service Linked Role”

In an account that has never used ECS, the stack can roll back with:

Resource handler returned message: "Invalid request provided: CreateCluster
Invalid Request: Unable to assume the service linked role. Please verify that
the ECS service linked role exists."

Create the role, then redeploy:

aws iam create-service-linked-role --aws-service-name ecs.amazonaws.com
aws iam get-role --role-name AWSServiceRoleForECS

If the first command returns Service role name AWSServiceRoleForECS has been taken in this account, the role already exists — often because the failed deployment triggered its creation. Confirm with get-role and redeploy.

Rollback Occurred

If CloudFormation rolled back:

1. Review the failure reason in the Events tab
2. Delete the failed stack
3. Fix the issue (service-linked role, certificate, permissions, etc.)
4. Restart deployment from Step 1