docs: deployment runbook — manual AWS setup steps before terraform apply

[tyrahappy]

Overview

Steps that must be done manually before terraform apply can succeed.
Run these in order — each step is a prerequisite for the next.

---

Step 1 — Create Terraform state bucket (one-time)

The S3 bucket that stores Terraform state must exist before terraform init can connect to the backend.

Option A: GitHub Actions (recommended)

1. Update GitHub Secrets with fresh Learner Lab credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
2. GitHub Actions → Terraform workflow → Run workflow → select bootstrap

Option B: Learner Lab terminal

aws s3api create-bucket \
  --bucket flair2-terraform-state \
  --region us-west-2 \
  --create-bucket-configuration LocationConstraint=us-west-2

aws s3api put-bucket-versioning \
  --bucket flair2-terraform-state \
  --versioning-configuration Status=Enabled

✅ One-time only — bucket persists across Learner Lab sessions.

---

Step 2 — Create API key secrets in Secrets Manager

ECS containers cannot use .env files. API keys are injected at container startup from Secrets Manager.

# Kimi (Moonshot) — primary reasoning provider
aws secretsmanager create-secret \
  --name flair2/dev/kimi-api-key \
  --secret-string "YOUR_KIMI_KEY_HERE" \
  --region us-west-2

# Gemini — video generation only
aws secretsmanager create-secret \
  --name flair2/dev/gemini-api-key \
  --secret-string "YOUR_GEMINI_KEY_HERE" \
  --region us-west-2

Each command returns an ARN like:

arn:aws:secretsmanager:us-west-2:123456789:secret:flair2/dev/kimi-api-key-AbCdEf

✅ One-time only — secrets persist across Learner Lab sessions.

---

Step 3 — Fill in secret ARNs in dev.tfvars

Open terraform/environments/dev.tfvars and replace the placeholder values:

kimi_api_key_secret_arn   = "arn:aws:secretsmanager:us-west-2:ACCOUNT:secret:flair2/dev/kimi-api-key-SUFFIX"
gemini_api_key_secret_arn = "arn:aws:secretsmanager:us-west-2:ACCOUNT:secret:flair2/dev/gemini-api-key-SUFFIX"

Commit and push the updated file.

---

Step 4 — Add GitHub Secrets (CI tests)

Go to repo → Settings → Secrets and variables → Actions:

Secret name	Value
AWS_ACCESS_KEY_ID	From Learner Lab "AWS Details"
AWS_SECRET_ACCESS_KEY	From Learner Lab "AWS Details"
AWS_SESSION_TOKEN	From Learner Lab "AWS Details"
GEMINI_API_KEY	Your Gemini API key

⚠️ AWS credentials expire every ~4-8 hours. Update before triggering plan/apply.

---

Step 5 — Run terraform apply

Trigger via GitHub Actions → Terraform workflow → Run workflow → select apply.

Or locally:

cd terraform
terraform init -backend-config="key=env/dev/terraform.tfstate"
terraform apply -var-file="environments/dev.tfvars"

---

Step 6 — Push Docker image to ECR

After terraform apply creates the ECR repositories:

# Get ECR login token
aws ecr get-login-password --region us-west-2 | \
  docker login --username AWS --password-stdin \
  $(aws sts get-caller-identity --query Account --output text).dkr.ecr.us-west-2.amazonaws.com

# Build and push
cd backend
docker build -t flair2-api .
docker tag flair2-api:latest ACCOUNT.dkr.ecr.us-west-2.amazonaws.com/flair2-dev-api:latest
docker push ACCOUNT.dkr.ecr.us-west-2.amazonaws.com/flair2-dev-api:latest

Replace ACCOUNT with your AWS account ID.

---

Checklist

• Step 1: S3 state bucket created (flair2-terraform-state)
• Step 2: Secrets created in Secrets Manager
• Step 3: ARNs filled in dev.tfvars and committed
• Step 4: GitHub Secrets configured (all 4)
• Step 5: terraform apply succeeded
• Step 6: Docker image pushed to ECR, ECS service healthy