AWS setup

SmartDeploy uses AWS for CodeBuild + ECR image builds, ECS Fargate runtime deployments, an Application Load Balancer (ALB) for HTTPS and custom-domain routing, STS for identity checks, and optionally ACM for TLS certificates on the ALB.

Use this guide together with:

• Custom domains — deployment hostnames and Vercel DNS
• Self-hosting — running SmartDeploy itself on EC2 (swap, SSL, Nginx)

1. Create an IAM user

1. Open IAM → Users → Create user.
2. Username: smartdeploy-service (or any name you prefer).
3. Select Provide user access to the AWS Management Console only if you want console access; it is not required for API access keys.
4. Click Next.

2. Attach a custom policy

Create a Customer managed policy with the JSON below, then attach it to the user.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "EC2",
      "Effect": "Allow",
      "Action": [
        "ec2:RunInstances",
        "ec2:TerminateInstances",
        "ec2:StartInstances",
        "ec2:StopInstances",
        "ec2:Describe*",
        "ec2:CreateTags",
        "ec2:CreateSecurityGroup",
        "ec2:DeleteSecurityGroup",
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:AuthorizeSecurityGroupEgress",
        "ec2:RevokeSecurityGroupIngress",
        "ec2:RevokeSecurityGroupEgress",
        "ec2:CreateKeyPair",
        "ec2:CreateLaunchTemplate",
        "ec2:DeleteLaunchTemplate"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ALB",
      "Effect": "Allow",
      "Action": [
        "elasticloadbalancingv2:*"
      ],
      "Resource": "*"
    },
    {
      "Sid": "SSM",
      "Effect": "Allow",
      "Action": [
        "ssm:SendCommand",
        "ssm:GetCommandInvocation",
        "ssm:DescribeInstanceInformation"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CodeBuildECR",
      "Effect": "Allow",
      "Action": [
        "codebuild:CreateProject",
        "codebuild:UpdateProject",
        "codebuild:StartBuild",
        "codebuild:BatchGetBuilds",
        "codebuild:BatchGetProjects",
        "ecr:GetAuthorizationToken",
        "ecr:BatchGetImage",
        "ecr:GetDownloadUrlForLayer",
        "ecr:InitiateLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload",
        "ecr:PutImage",
        "ecr:CreateRepository",
        "ecr:DescribeRepositories",
        "ecr:BatchCheckLayerAvailability"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CloudWatchLogs",
      "Effect": "Allow",
      "Action": [
        "logs:GetLogEvents",
        "logs:DescribeLogGroups",
        "logs:DescribeLogStreams"
      ],
      "Resource": "*"
    },
    {
      "Sid": "IAM",
      "Effect": "Allow",
      "Action": [
        "iam:GetRole",
        "iam:CreateRole",
        "iam:PassRole",
        "iam:AttachRolePolicy",
        "iam:CreateInstanceProfile",
        "iam:AddRoleToInstanceProfile",
        "iam:GetInstanceProfile",
        "iam:CreateServiceLinkedRole"
      ],
      "Resource": "*"
    },
    {
      "Sid": "STS",
      "Effect": "Allow",
      "Action": "sts:GetCallerIdentity",
      "Resource": "*"
    }
  ]
}

Why wildcards? The app creates and discovers resources dynamically (security groups, listeners, target groups, CodeBuild projects). You can narrow Resource to your account or region if your organization requires it.

3. Access keys and environment variables

3.1 Long-lived access keys (local dev, Docker, non-AWS hosts)

1. Open the user → Security credentials → Create access key.
2. Use case: Application running outside AWS.
3. Copy the Access key ID and Secret access key (shown once).

In .env (see also .env.example):

When STATIC_SITE_BUCKET and STATIC_SITE_PUBLIC_BASE_URL are set, sd-artifacts scans with deploy_shape: static or static_build (no start command) use CodeBuild → S3 instead of ECR/ECS.

Container deploys (Railpack server, existing_docker) require the ECS variables above. Static deploys require the STATIC_SITE_* variables.

3.2 Platform infrastructure (Terraform)

Instead of creating the S3 bucket, CloudFront distribution, ECS cluster, and Fargate networking by hand, use the Terraform stack:

cd infra/smart-deploy-platform
cp terraform.tfvars.example terraform.tfvars
terraform init && terraform apply
terraform output -raw smart_deploy_env_snippet

Paste the snippet into .env. If you already created the bucket or cluster manually, set create_s3_bucket = false and/or create_ecs_cluster = false in terraform.tfvars (see infra/smart-deploy-platform/README.md).

If the Next.js app and worker run on EC2, attach an IAM role with the same policy instead of embedding keys. Leave AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY unset; the AWS SDK uses the instance metadata role automatically.

1. IAM → Roles → Create role → AWS service → EC2.
2. Attach the custom policy from §2.
3. EC2 → instance → Actions → Security → Modify IAM role → select the role.

Details: Self-hosting.

4. HTTPS on the ALB (ACM)

1. Open ACM in the same region as AWS_REGION.
2. Request a public certificate (wildcard or hostname you will use).
3. Complete DNS validation.
4. Set DEPLOYMENT_ACM_CERTIFICATE_ARN in .env.

SmartDeploy creates an HTTPS (443) listener and can redirect HTTP to HTTPS. More context: Custom domains.

5. Optional: AWS Bedrock (LLM)

To use Bedrock instead of or alongside Gemini, add credentials that include bedrock:InvokeModel (same IAM user or a dedicated user):

AWS_BEDROCK_ACCESS_KEY_ID=AKIA...
AWS_BEDROCK_SECRET_ACCESS_KEY=...
BEDROCK_MODEL_ID=anthropic.claude-opus-4-5-v1:0

Extend the IAM policy with Bedrock invoke permissions if you use a separate key.

Troubleshooting

Security tips

• Do not use the AWS account root user for application keys.
• Rotate access keys on a schedule.
• Prefer an EC2 instance role over static keys when self-hosting.
• Enable CloudTrail for API auditing.