Initial Setup

After deploying AlertD to your AWS environment, you need to complete the initial application setup. This includes authenticating your team and creating an IAM role for AWS resource access.

Overview

The initial setup process consists of two phases:

Phase 1: Authentication Setup

Step 1: Access the AlertD Application

1. Open the AlertDApplicationURL from your CloudFormation stack outputs
   • Format: https://AlertD-S-Alb-xxxx.us-west-1.elb.amazonaws.com
   • Or your custom domain if you configured DNS mapping
2. You’ll see the AlertD welcome screen with authentication options

Step 2: Choose Authentication Provider

AlertD supports two authentication methods:

• Continue with Google – Authenticate using your Google account
• Continue with GitHub – Authenticate using your GitHub account

Click your preferred authentication method to proceed.

Step 3: Complete OAuth Flow

1. A popup window will open showing your Google or GitHub login
2. For Google:
   • Select the account you want to use for AlertD
   • Click “Continue” to authorize
3. For GitHub:
   • Authorize the AlertD application
   • Grant necessary permissions
4. You’ll be redirected back to AlertD once authentication is complete

Step 4: Verify Workspace Configuration

After successful authentication:

1. AlertD displays a confirmation screen showing:
   • Successfully Connected – Green checkmark confirming your OAuth connection
   • Super User Email – Your authenticated email address (e.g., gaston@alertd.ai)
   • Allowed Domain – The domain associated with your workspace (e.g., alertd.ai)
2. Your identity is automatically linked to a team workspace
3. All users with the same email domain will share this workspace
4. Workspace boundaries are enforced at the session and data layer

Click Continue Setup to proceed to AWS configuration.

Phase 2: AWS Configuration

AlertD needs read-only access to your AWS resources to answer questions about your infrastructure. You’ll create an IAM role with the ReadOnlyAccess managed policy.

Understanding the Access Model

AlertD uses:

• Ephemeral STS tokens (not permanent credentials)
• AWS ReadOnlyAccess managed policy (no write permissions)
• Cross-account AssumeRole pattern (AWS best practice)
• Immediately revocable access (remove IAM role anytime)

Step 5: Review AWS Configuration Requirements

The AlertD setup wizard displays the AWS configuration section with instructions you will use to set up access to your AWS account.

Step 6: Review Trust Policy

The trust policy displayed on screen shows:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::837098207881:role/AlertD-Stack-TaskRole-..."
      },
      "Action": "sts:AssumeRole",
      "Condition": {....}
    }
  ]
}

Key elements:

• Principal AWS ARN – The AlertD ECS task role (from your CloudFormation stack)
• Action – sts:AssumeRole (allows AlertD to temporarily assume your role)
• Effect – Allow (grants permission)
• Condition - Specifies a session name for role assumption.

You’ll copy this trust policy in the next steps.

Phase 3: Create the IAM Role

Step 7: Open AWS IAM Console

1. Open a new browser tab
2. Navigate to the AWS IAM Console: https://console.aws.amazon.com/iam/home 
3. Ensure you’re in the same AWS account where you deployed AlertD
4. The IAM Dashboard displays your current roles, policies, and users

5. In the left sidebar, click Roles
6. Click the Create role button in the top right

Step 8: Select Custom Trust Policy

1. On the Select trusted entity page, you’ll see several options:

   • AWS service
   • AWS account
   • Web identity
   • SAML 2.0 federation
   • Custom trust policy ← Select this option

2. Click Custom trust policy (highlighted with a red border)

Step 9: Paste the Trust Policy

1. Return to the AlertD setup tab
2. Copy the entire Trust Policy JSON from the AlertD screen
3. Return to the AWS IAM Console tab
4. Paste the trust policy into the Custom trust policy editor
5. The policy should show:
   • Version: "2012-10-17"
   • Principal AWS ARN matching your AlertD deployment
   • Action: "sts:AssumeRole"
6. Click Next at the bottom of the page

Step 10: Add Permissions

1. On the Add permissions page, you’ll see a list of AWS managed policies
2. Click the Filter by Type dropdown
3. Select AWS managed - job function
4. This filters to AWS-curated policies for specific job roles

5. In the search box or policy list, find ReadOnlyAccess
6. Check the box next to ReadOnlyAccess
   • This AWS-managed policy provides read permissions across all AWS services
   • It includes CloudWatch, EC2, S3, RDS, and 100+ other services
7. Click Next to proceed to naming

Step 11: Name the Role

1. On the Name, review, and create page:
2. Role name: Enter AlertD-Role (or your preferred name)
3. (Optional) Description: Add a note like “Read-only access for AlertD agent”
4. Review the Trust policy and Permissions policies sections
5. Verify that:
   • Trust policy shows the correct Principal ARN
   • Permissions list includes ReadOnlyAccess
6. Click Create role at the bottom

Step 12: Copy the Role ARN

1. After role creation, you’ll see a green success banner: “Role AlertD-Role created”
2. Click View role to open the role details

3. The role summary page displays:
   • Role name
   • Creation date
   • Permissions policies (ReadOnlyAccess)
   • Trust relationships

4. Locate the ARN field in the summary section
5. The ARN format: arn:aws:iam::837098207881:role/AlertD-Role
6. Click the copy icon next to the ARN to copy it to your clipboard

Phase 4: Complete AlertD Configuration

Step 13: Enter Role ARN in AlertD

1. Return to the AlertD setup tab in your browser
2. Paste the Role ARN you copied into the Role ARN field
   • Example: arn:aws:iam::837098207881:role/AlertD-Role
3. Select your AWS Region from the dropdown
   • Choose the region where most of your resources reside
   • Example: us-west-1, us-east-1, eu-west-1
4. Click Continue Setup

AlertD will now:

• Validate the IAM role ARN
• Test the AssumeRole permissions
• Verify it can access CloudWatch
• Initialize the workspace

Step 14: Wait for Setup Completion

1. AlertD validates the connection and finalizes deployment
2. You’ll see a Setup Complete! message with:
   • Green checkmark icon
   • “Your AlertD deployment is ready to use.”
   • Progress indicator: “Connecting to AlertD” with attempt counter
3. Wait for services to be ready; this step usually takes around three minutes.

Step 15: Access the AlertD Dashboard

Once setup completes, you’re automatically redirected to the AlertD workspace:

Sidebar sections:

• My Activity – Your personal chat sessions and queries
• Tags – Organizational tags for sessions
• Team Activity – Shared sessions from your workspace teammates

Main workspace:

• New session button – Start asking questions
• Region selector – Choose AWS region (defaults to “All Regions”)
• Search bar – “Ask whatever you want” prompt

You’re now ready to ask your first question!

✅ Setup Complete!

Your AlertD deployment is fully configured and ready to use. You now have:

• ✓ Authenticated workspace with team access
• ✓ AWS IAM role with read-only permissions to CloudWatch
• ✓ Access to the AlertD web interface

Troubleshooting

Authentication Issues

Problem: Cannot authenticate with Google or GitHub

Solutions:

• Ensure popup blockers are disabled
• Try a different browser
• Check that auth.demo.alertd.ai is accessible from your network
• Clear browser cache and cookies

Problem: After logging into Google/Github, you reach the following screen error:

Solutions:

• This is a known bug. Return to the previous screen and reauthenticate. We are actively working to fix this issue.

IAM Role Issues

Problem: AlertD cannot assume the IAM role

Solutions:

• Verify the trust policy includes the correct Principal ARN
• Ensure you copied the full Role ARN (starts with arn:aws:iam::)
• Wait 30-60 seconds for IAM changes to propagate if you created the role in a different region.

Problem: “Access Denied” errors when querying AWS

Solutions:

• Verify ReadOnlyAccess policy is attached to the role
• Check that the IAM role has no permission boundaries restricting access
• Ensure your AWS account has no SCPs blocking read operations

Connection Issues

Problem: Setup completion hangs or times out

Solutions:

• Verify ECS tasks are running in your CloudFormation stack
• Check security group rules allow traffic between ALB and ECS tasks
• Ensure private subnets have NAT Gateway for outbound internet access
• Review CloudWatch logs for the AlertD ECS tasks