Initial Setup

Complete guide to setting up your development environment for the NorthBuilt RAG System.

Prerequisites

Required Tools

Tool	Minimum Version	Installation
Terraform	1.13.0+	Download
AWS CLI	2.0+	Install Guide
GitHub CLI	Latest	brew install gh
Python	3.13+	brew install python@3.13
Git	Latest	brew install git

AWS Account Setup

1. Create AWS Account

If you don’t have an AWS account:

1. Go to https://aws.amazon.com
2. Click “Create an AWS Account”
3. Follow the setup wizard

2. Configure AWS Credentials

aws configure

Provide:

• AWS Access Key ID
• AWS Secret Access Key
• Default region: us-east-1
• Default output format: json

3. Request Bedrock Model Access

AWS Bedrock requires explicit model access approval:

1. Open AWS Console → Bedrock
2. Navigate to “Model access”
3. Request access to:
   • amazon.titan-embed-text-v2:0 (embeddings)
   • us.anthropic.claude-sonnet-4-5-20250929-v1:0 (LLM)
4. Wait for approval (usually instant for these models)

External Service Accounts

Create accounts for these services:

Fathom (Optional)

1. Sign up at https://app.fathom.video
2. Go to Settings → API
3. Generate API key

HelpScout (Optional)

1. Sign up at https://www.helpscout.com
2. Go to Your Profile → My Apps → API Keys
3. Generate API key

Linear (Optional)

1. Sign up at https://linear.app
2. Go to Settings → API → Personal API Keys
3. Generate API key

Google OAuth (Required for Web UI)

1. Go to https://console.cloud.google.com
2. Create a project (or use existing)
3. Enable Google+ API
4. Go to APIs & Services → Credentials
5. Create OAuth 2.0 Client ID:
   • Type: Web application
   • Name: NorthBuilt RAG System
   • Authorized redirect URIs: (Add after Cognito is deployed)
     • https://nb-rag-sys-auth.auth.us-east-1.amazoncognito.com/oauth2/idpresponse
     • http://localhost:8080/callback.html (for local dev)
6. Save Client ID and Client Secret

Repository Setup

Clone Repository

git clone https://github.com/craftcodery/compass.git
cd compass

Install Python Dependencies (for local development)

cd lambda/chat
python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt

Verify Setup

Check Tool Versions

# Terraform
terraform version
# Should output: Terraform v1.13.0 or higher

# AWS CLI
aws --version
# Should output: aws-cli/2.x.x or higher

# GitHub CLI
gh --version
# Should output: gh version 2.x.x or higher

# Python
python3 --version
# Should output: Python 3.13.x or higher

Verify AWS Credentials

aws sts get-caller-identity

Should output your AWS account ID, user ARN, and user ID.

Test AWS Bedrock Access

aws bedrock list-foundation-models --region us-east-1 --by-provider anthropic

Should list available Claude models.

Environment Variables

For local development, set these environment variables:

# AWS (if not using aws configure)
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION=us-east-1

# Secrets (optional - for webhook integrations)
export TF_VAR_fathom_api_key_value="..."
export TF_VAR_google_client_id="..."
export TF_VAR_google_client_secret="..."

Or create a .env file (add to .gitignore!):

cat > .env << 'SECRETS'
AWS_REGION=us-east-1
TF_VAR_fathom_api_key_value=...
TF_VAR_google_client_id=...
SECRETS

# Load environment
source .env

Next Steps

For Local Development

Continue to Local Development Guide

For Deployment

Continue to Bootstrap Guide

Troubleshooting

AWS CLI Not Found

# macOS
brew install awscli

# Linux
pip3 install awscli --upgrade --user

Terraform Not Found

# macOS
brew install terraform

# Linux
wget https://releases.hashicorp.com/terraform/1.13.0/terraform_1.13.0_linux_amd64.zip
unzip terraform_1.13.0_linux_amd64.zip
sudo mv terraform /usr/local/bin/

Bedrock Model Access Denied

• Ensure you requested access in AWS Console → Bedrock → Model access
• Wait a few minutes for approval to propagate
• Try in a different region if needed

AWS Credentials Invalid

# Reconfigure
aws configure

# Or check existing config
cat ~/.aws/credentials
cat ~/.aws/config

---

Last updated: 2025-12-29