Pre-Deployment Checklist

Complete checklist of manual requirements before Terraform automation can succeed.

Overview

While most infrastructure is automated via Terraform, certain prerequisites must be configured manually before deployment. This checklist ensures all dependencies are met.

Checklist

1. AWS Account Setup

  • AWS Account Created
    • Sign up at https://aws.amazon.com
    • Verify email address
    • Add payment method
  • AWS CLI Configured 
    aws configure
# Verify: aws sts get-caller-identity
    • AWS Access Key ID
    • AWS Secret Access Key
    • Default region: us-east-1
    • Default output format: json
  • Sufficient IAM Permissions
    • Admin access OR specific permissions for:
      • Lambda, API Gateway, Cognito
      • S3, DynamoDB, Secrets Manager
      • CloudFront, CloudWatch, IAM
      • Bedrock (model invocation)
  • AWS Bedrock Model Access Approved
    • Navigate to: AWS Console → Bedrock → Model access
    • Request access to:
      • amazon.titan-embed-text-v2:0 (embeddings)
      • us.anthropic.claude-sonnet-4-5-20250929-v1:0 (LLM)
    • Wait for approval (usually instant)
    • Verify: 
      aws bedrock list-foundation-models --region us-east-1 --by-provider anthropic

2. External Service Accounts

  • Google OAuth Credentials (Required)
    • Navigate to: https://console.cloud.google.com
    • Create project (or use existing)
    • Enable Google+ API (or Google Identity)
    • Go to: APIs & Services → Credentials
    • Create OAuth 2.0 Client ID:
      • Type: Web application
      • Name: NorthBuilt RAG System
      • Authorized redirect URIs: (Add after Cognito deployment)
        • https://nb-rag-sys-auth.auth.us-east-1.amazoncognito.com/oauth2/idpresponse
        • http://localhost:8080/callback.html (for local testing)
    • Save Client ID
    • Save Client Secret
    • Note: Redirect URI must be updated after Cognito user pool is created
  • Fathom Account (Optional)
    • Sign up: https://app.fathom.video
    • Navigate to: Settings → API
    • Generate API key
    • Save API key
  • HelpScout Account (Optional)
    • Sign up: https://www.helpscout.com
    • Navigate to: Your Profile → My Apps → API Keys
    • Generate API key
    • Save API key
  • Linear Account (Optional)
    • Sign up: https://linear.app
    • Navigate to: Settings → API → Personal API Keys
    • Generate API key
    • Save API key

3. GitHub Repository Setup

  • GitHub Repository Created
    • Repository: craftcodery/compass
    • Visibility: Public or Private
    • Initialized with README
  • GitHub CLI Installed 
    brew install gh
# Verify: gh --version
  • GitHub CLI Authenticated 
    gh auth login
# Verify: gh auth status

4. Local Development Tools

  • Terraform Installed 
    brew install terraform
# Verify: terraform version
# Required: >= 1.13.0
  • Python Installed 
    brew install python@3.13
# Verify: python3 --version
# Required: >= 3.13
  • Git Installed 
    brew install git
# Verify: git --version

5. Bootstrap Infrastructure

  • S3 Bucket for Terraform State
    • Bucket name: nb-rag-sys-terraform-state
    • Region: us-east-1
    • Versioning: Enabled
    • Encryption: AES-256
    • Public access: Blocked
    • Created via: 
      ./.github/setup-oidc.sh
# OR
cd bootstrap && terraform apply
  • DynamoDB Table for State Locking
    • Table name: nb-rag-sys-terraform-locks
    • Primary key: LockID (String)
    • Billing mode: On-demand
    • PITR: Enabled
    • Created via same bootstrap process
  • GitHub OIDC Provider
    • URL: https://token.actions.githubusercontent.com
    • Client ID: sts.amazonaws.com
    • Created in AWS IAM
    • Verify: 
      aws iam list-open-id-connect-providers
  • GitHub Actions IAM Role
    • Role name: GitHubActionsOIDCRole
    • Trust policy: GitHub OIDC provider
    • Permissions: Terraform deployment
    • Verify: 
      aws iam get-role --role-name GitHubActionsOIDCRole

6. GitHub Secrets Configuration

  • AWS_ROLE_ARN 
    gh secret set AWS_ROLE_ARN --body "arn:aws:iam::ACCOUNT_ID:role/GitHubActionsOIDCRole"
  • GOOGLE_CLIENT_ID 
    gh secret set GOOGLE_CLIENT_ID --body "123456789.apps.googleusercontent.com"
  • GOOGLE_CLIENT_SECRET 
    gh secret set GOOGLE_CLIENT_SECRET --body "GOCSPX-..."
  • FATHOM_API_KEY (Optional) 
    gh secret set FATHOM_API_KEY --body "..."
  • HELPSCOUT_API_KEY (Optional) 
    gh secret set HELPSCOUT_API_KEY --body "..."
  • LINEAR_API_KEY (Optional) 
    gh secret set LINEAR_API_KEY --body "..."
  • Verify Secrets 
    gh secret list
# Should show all secrets (values hidden)

7. Terraform Configuration

  • Backend Configuration Updated
    • File: terraform/backend.tf
    • Bucket matches bootstrap bucket name
    • DynamoDB table matches bootstrap table name
    • Region is correct
  • Variables File Created
    • File: terraform/terraform.tfvars (gitignored)
    • OR environment variables set: 
      export TF_VAR_google_client_id="..."
export TF_VAR_google_client_secret="..."
  • Terraform Initialized 
    cd terraform
terraform init
# Should download providers and configure backend

8. Network & DNS (Optional - for Custom Domain)

  • Domain Registered
    • Domain: yourdomain.com
    • Registrar: Any (Route53, Namecheap, etc.)
  • Route53 Hosted Zone Created 
    aws route53 create-hosted-zone --name yourdomain.com --caller-reference $(date +%s)
  • Domain Nameservers Updated
    • Point to Route53 nameservers
    • Verify DNS propagation: 
      dig NS yourdomain.com
  • ACM Certificate Requested
    • Region: us-east-1 (required for CloudFront)
    • Domain: yourdomain.com + *.yourdomain.com
    • Validation: DNS (recommended)
    • Status: Issued
    • Verify: 
      aws acm list-certificates --region us-east-1

Verification Script

Run this script to verify all prerequisites:

#!/bin/bash

echo "=== Pre-Deployment Verification ==="

# Check AWS CLI
if ! command -v aws &> /dev/null; then
  echo "[ERROR] AWS CLI not installed"
else
  echo "[OK] AWS CLI installed: $(aws --version)"
fi

# Check AWS credentials
if aws sts get-caller-identity &> /dev/null; then
  echo "[OK] AWS credentials configured"
  aws sts get-caller-identity
else
  echo "[ERROR] AWS credentials not configured"
fi

# Check Bedrock access
if aws bedrock list-foundation-models --region us-east-1 --by-provider anthropic &> /dev/null; then
  echo "[OK] Bedrock access enabled"
else
  echo "[ERROR] Bedrock access not enabled"
fi

# Check Terraform
if ! command -v terraform &> /dev/null; then
  echo "[ERROR] Terraform not installed"
else
  echo "[OK] Terraform installed: $(terraform version -json | jq -r '.terraform_version')"
fi

# Check GitHub CLI
if ! command -v gh &> /dev/null; then
  echo "[ERROR] GitHub CLI not installed"
else
  echo "[OK] GitHub CLI installed: $(gh --version | head -n1)"
fi

# Check GitHub authentication
if gh auth status &> /dev/null; then
  echo "[OK] GitHub authenticated"
else
  echo "[ERROR] GitHub not authenticated"
fi

# Check GitHub secrets
echo "GitHub Secrets:"
gh secret list

# Check S3 bucket
if aws s3 ls s3://nb-rag-sys-terraform-state &> /dev/null; then
  echo "[OK] Terraform state bucket exists"
else
  echo "[ERROR] Terraform state bucket does not exist"
fi

# Check DynamoDB table
if aws dynamodb describe-table --table-name nb-rag-sys-terraform-locks &> /dev/null; then
  echo "[OK] Terraform lock table exists"
else
  echo "[ERROR] Terraform lock table does not exist"
fi

# Check OIDC provider
if aws iam list-open-id-connect-providers | grep -q "token.actions.githubusercontent.com"; then
  echo "[OK] GitHub OIDC provider exists"
else
  echo "[ERROR] GitHub OIDC provider does not exist"
fi

# Check IAM role
if aws iam get-role --role-name GitHubActionsOIDCRole &> /dev/null; then
  echo "[OK] GitHub Actions IAM role exists"
else
  echo "[ERROR] GitHub Actions IAM role does not exist"
fi

echo "=== Verification Complete ==="

Save as scripts/verify-prerequisites.sh and run:

chmod +x scripts/verify-prerequisites.sh
./scripts/verify-prerequisites.sh

Common Issues

Issue: Bedrock Access Denied

Symptom: AccessDeniedException when invoking Bedrock models

Solution:

  1. Navigate to AWS Console → Bedrock → Model access
  2. Ensure both Titan and Claude models show “Access granted”
  3. Wait 5-10 minutes for permissions to propagate
  4. Try again

Issue: Knowledge Base Sync Not Working

Symptom: Documents not appearing in search results

Solution:

  1. Verify documents are in the S3 documents bucket
  2. Check Knowledge Base sync status in AWS Console
  3. Trigger manual sync if needed via Bedrock console
  4. Wait 5-10 minutes for indexing to complete

Issue: Google OAuth Redirect Mismatch

Symptom: redirect_uri_mismatch error during login

Solution:

  1. Get Cognito domain from Terraform output: 
    terraform output cognito_domain
  2. Add redirect URI to Google OAuth:
    • https://[cognito-domain].auth.us-east-1.amazoncognito.com/oauth2/idpresponse
  3. Wait a few minutes for Google to propagate changes
  4. Try again

Issue: GitHub Actions Permission Denied

Symptom: AccessDenied in GitHub Actions workflow

Solution:

  1. Verify IAM role exists and has correct trust policy
  2. Update IAM policy with latest permissions: 
    ./.github/setup-oidc.sh
  3. Check GitHub secret AWS_ROLE_ARN is correct
  4. Re-run workflow

Ready to Deploy?

Once all checklist items are complete, proceed to deployment:

# Option 1: Deploy via GitHub Actions (recommended)
git push origin main

# Option 2: Deploy locally
cd terraform
terraform plan
terraform apply

Last updated: 2026-01-01