Deployment Guide

Complete guide to deploying the NorthBuilt RAG System.

Quick Start

  1. Run OIDC setup (one-time): 
    ./.github/setup-oidc.sh
  2. Add GitHub Secrets: 
    gh secret set AWS_ROLE_ARN --body "arn:aws:iam::ACCOUNT:role/GitHubActionsOIDCRole"
gh secret set FATHOM_API_KEY --body "..."
gh secret set GOOGLE_CLIENT_ID --body "..."
gh secret set GOOGLE_CLIENT_SECRET --body "..."
  3. Deploy: 
    git push origin main

Manual Deployment 

# Set environment variables
export TF_VAR_google_client_id="..."
export TF_VAR_google_client_secret="..."
# ... other secrets as needed

# Deploy
cd terraform
terraform init
terraform plan
terraform apply

OIDC Authentication

GitHub Actions uses OIDC to authenticate with AWS:

  1. GitHub requests JWT token
  2. AWS validates token
  3. AWS issues temporary credentials (~1 hour)
  4. Terraform runs with temp credentials
  5. Credentials expire after workflow

Monitoring Deployments 

# Watch deployment
gh run watch

# View logs
gh run view --log

# List recent runs
gh run list --workflow=terraform-deploy.yml

Troubleshooting

Permission Denied

Update IAM policy:

./.github/setup-oidc.sh
gh run rerun --failed

State Lock 

terraform force-unlock LOCK_ID

Resource Exists 

terraform import 'module.path.resource' 'resource-id'

See Troubleshooting Guide for more details