### **AWS Configuration Guide**

This guide provides detailed instructions for setting up AWS credentials, understanding the required permissions, and configuring your environment for the UF r/place project.

## Create an AWS Account

If you don't have an AWS account:
1. Visit [aws.amazon.com](https://aws.amazon.com/)
2. Click "Create an AWS Account"
3. Follow the registration process
4. **Important**: You'll need a credit card, but most usage will fall under the free tier

## AWS Credentials Setup

You need AWS credentials to deploy infrastructure. Below is the easiest method for personal accounts to setup their AWS Account and CLI for this project.

### Create Access Keys

1. **Sign in to AWS Console** at [console.aws.amazon.com](https://console.aws.amazon.com/)

2. **Navigate to IAM**:
   - In the search bar, look up "IAM" and click the first option.

3. **Create User**:
   - Scroll to Access management > Users (in the sidebar)
   - Create a new user if you don't already have one
   - Give the user a name (eg. "uf-r-place")
   - After you create the user click on the name
   - Go to the permissions tab and click Add permissions > Add permissions
      - Click "Attach policies directly"

4. **Select all of these option for the new user**

PolicyNames:
- [x] AWSLambda_FullAccess
- [x] AmazonAPIGatewayAdministrator
- [x] IAMFullAccess
- [x] AWSCloudFormationFullAccess
- [x] AmazonS3FullAccess
- [x] AmazonEC2ContainerRegistryFullAccess
- [x] AmazonSSMFullAccess
- [x] CloudWatchFullAccess


5. **Create Access Key**
- After creating your user, at the top, click "Create Access Key"
- Select CLI as your use case
- Copy the keys and download them!!

> [!IMPORTANT]
> Once you finish selecting the above options and creating the access key copy both the Access Key ID and Secret Access Key immediately. Download the CSV file as backup.
> ```bash
> # These are examples but you should save yours somewhere in a file like this
> SECRET_KEY="EBaaekjbGEKjbEKGElGEbLEKJgE/373nEWKJgEBlkJEG"
> ACCESS_KEY="AFKEJRBFLJEBFLJAJBGE"
> ```

### Environment Variables

The CDK deployment uses environment variables that require setup as well. After cloning the repository, make a copy of `infra/.env.example` at `infra/.env`. And in it set the following:

```bash
# Required: Your AWS account ID (12 digits)
CDK_ACCOUNT=123456789012
CDK_REGION=us-east-1
```

### Configure AWS CLI

1. **Install AWS CLI**:
   
   For macOS (using Homebrew):
   ```bash
   brew install awscli
   ```
   
   For Linux/Windows, download from AWS:

   https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html
   

2. **Configure AWS CLI**:
   ```bash
   aws configure
   ```
   
   You'll be prompted for:
   - **AWS Access Key ID**: Your access key
   - **AWS Secret Access Key**: Your secret key  
   - **Default region name**: `us-east-1`
   - **Default output format**: `json`

   The steps to create these keys are in the 'Create Access Keys' section. 
   
   You may change Default region name, or output format, but these are the recommended values.

3. **Verify setup**:
   ```bash
   aws sts get-caller-identity
   ```

### Test AWS Cli Configuration

Test your AWS account and CLI is setup via bootstrapping your project (which is required only once per project)

```
npm run cdk:bootstrap
```

Then deploy your app via

```
npm run deploy
```

**Important**: Save the `ApiUrl` output from this command - you'll need it in the next step.

## Environment File Setup

### Frontend Environment Variables

Create `web/.env.local` with your API URL:

```bash
# Replace with your actual API Gateway URL
NEXT_PUBLIC_API_URL=https://abc123def4.execute-api.us-east-1.amazonaws.com/prod/
```

**Important Notes:**
- The URL must end with a trailing slash `/`
- This file is git-ignored (never commit it)
- Use `NEXT_PUBLIC_` prefix for client-side variables


## Best Practices

### Access Key Security

- **Never commit** AWS credentials to version control
- **Rotate keys regularly** (every 90 days recommended)
- **Use least privilege** - only grant necessary permissions
- **Enable MFA** for your AWS account
- **Use temporary credentials** when possible

### CDK Bootstrap Security

The CDK bootstrap creates resources in your AWS account:
- **S3 bucket** for storing templates and assets
- **IAM roles** for CloudFormation execution
- **SSM parameters** for configuration

These are secure by default and required for CDK operation.

## Troubleshooting

### "Unable to resolve AWS account to use"

```bash
# Check if credentials are configured
aws sts get-caller-identity

# If this fails, reconfigure:
aws configure

# Or set environment variables:
CDK_ACCOUNT=123456789012
CDK_REGION=us-east-1
```

### "Access Denied" Errors

1. **Check permissions** - Your IAM user needs the required policies
2. **Verify region** - Make sure you're deploying to the intended region
3. **Check account ID** - Ensure CDK_ACCOUNT matches your actual account

### "Region not supported"

Some AWS services aren't available in all regions. Stick to major regions like:
- `us-east-1`, `us-west-2`
- `eu-west-1`, `eu-central-1`  
- `ap-southeast-1`, `ap-northeast-1`

### Bootstrap Issues

**"User is not authorized to perform: ecr:CreateRepository"**

This error occurs when your IAM user lacks permissions to create ECR repositories during CDK bootstrap:

```bash
# Solution 1: Add the missing ECR permissions
aws iam attach-user-policy --user-name your-username --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryFullAccess

# Solution 2: Add SSM permissions if you also see SSM errors
aws iam attach-user-policy --user-name your-username --policy-arn arn:aws:iam::aws:policy/AmazonSSMFullAccess

# Then retry bootstrap
npm run cdk:bootstrap
```

**CDK Bootstrap Failed - General Recovery**

```bash
# Re-run bootstrap if it fails
npm run cdk:bootstrap

# Check what resources were created
aws cloudformation describe-stacks --stack-name CDKToolkit

# If bootstrap partially failed, clean up and retry
aws cloudformation delete-stack --stack-name CDKToolkit
# Wait for deletion to complete, then retry
npm run cdk:bootstrap
```

**Environment Variables Missing**

```bash
# Make sure these are set before bootstrap
export CDK_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
export CDK_REGION=$(aws configure get region)

# Verify they're set correctly
echo "Account: $CDK_ACCOUNT"
echo "Region: $CDK_REGION"

# Then bootstrap
npm run cdk:bootstrap
```

**Cleanup/Destroy Issues**

```bash
# If destroy hangs or fails, check the CloudFormation console
aws cloudformation describe-stack-events --stack-name UfRPlaceBackend

# Force delete stuck resources (careful!)
aws cloudformation delete-stack --stack-name UfRPlaceBackend

# If CDK bootstrap cleanup fails
aws cloudformation describe-stack-events --stack-name CDKToolkit

# Clean up individual resources if stack delete fails
aws s3 rb s3://cdktoolkit-stagingbucket-* --force  # Replace with actual bucket name
aws cloudformation delete-stack --stack-name CDKToolkit
```

## Cost Management

### Free Tier Usage

Monitor your AWS usage to stay within free tier:
1. Set up **billing alerts** in AWS Console
2. Use **AWS Cost Explorer** to track spending  
3. Enable **free tier usage alerts**

### Resource Cleanup

To avoid ongoing costs, you can clean up resources at different levels.

Note, that if you destroy and deploy, you will need to reset your `web/.env` api url to the new deployment.

#### Option 1: Destroy Project Resources Only (Recommended)

```bash
# Remove all project resources (keeps CDK bootstrap resources)
npm run destroy

# This removes:
# - Lambda functions
# - API Gateway  
# - IAM roles created by the project
# - CloudWatch log groups (after retention period)
# - CloudFormation stack (UfRPlaceBackend)
```

#### Option 2: Complete Cleanup (Everything)

```bash
# 1. First destroy the project resources
npm run destroy

# 2. Then remove CDK bootstrap resources (optional - only if you won't use CDK again)
aws cloudformation delete-stack --stack-name CDKToolkit

# 3. Verify all stacks are deleted
aws cloudformation list-stacks --stack-status-filter DELETE_COMPLETE --query 'StackSummaries[?contains(StackName, `CDK`) || contains(StackName, `UfRPlace`)].{Name:StackName,Status:StackStatus}' --output table
```

#### What Gets Deleted

**Project Resources (`npm run destroy`):**
- Lambda function and execution role
- API Gateway REST API
- CloudWatch log groups (after retention)
- CloudFormation stack
- **Cost**: $0 (everything is within free tier)

**CDK Bootstrap Resources (`CDKToolkit` stack):**
- S3 bucket for CDK assets 
- IAM roles for CloudFormation
- SSM parameters for configuration
- ECR repository for container assets
- **Cost**: ~$0.02/month for S3 storage

#### Verification Commands

```bash
# Check remaining stacks
aws cloudformation list-stacks --stack-status-filter CREATE_COMPLETE UPDATE_COMPLETE

# Check for remaining Lambda functions
aws lambda list-functions --query 'Functions[?starts_with(FunctionName, `UfRPlace`)].FunctionName'

# Check for remaining API Gateways
aws apigateway get-rest-apis --query 'items[?name==`UfRPlaceApi`].{Name:name,Id:id}'
```