Setup Guide

Get started with the NorthBuilt RAG System - from understanding what it does to deploying it on AWS.

Table of contents

  1. Overview
  2. Documents
    1. 1. Project Overview
    2. 2. Initial Setup
    3. 3. Pre-Deployment Checklist
    4. 4. Bootstrap Guide
  3. Recommended Reading Order
    1. For New Engineers
    2. For DevOps
    3. For Architects
  4. Next Steps
  5. Common Setup Issues
    1. AWS Bedrock Access Denied
    2. Bedrock Knowledge Base Sync Issues
    3. GitHub Actions Permission Denied

Overview

This section covers everything you need to get the system up and running:

  • Understanding the system architecture and capabilities
  • Configuring your development environment
  • Verifying all prerequisites before deployment
  • Setting up AWS foundation infrastructure

Documents

1. Project Overview

Start here - Comprehensive introduction to the NorthBuilt RAG System.

Learn about:

  • Core capabilities and use cases
  • System architecture overview
  • Technology stack
  • Performance characteristics
  • Cost structure

Audience: All team members Time: 15 minutes

2. Initial Setup

Configure your local development environment.

Covers:

  • Prerequisites (AWS CLI, Terraform, Python, etc.)
  • AWS account setup
  • Bedrock model access approval
  • External service accounts (Google OAuth, etc.)
  • Repository setup

Audience: Engineers, DevOps Time: 30-45 minutes

3. Pre-Deployment Checklist

Complete checklist of manual requirements before Terraform can deploy.

Includes:

  • AWS account configuration
  • External service accounts
  • GitHub repository setup
  • Bootstrap infrastructure
  • GitHub secrets configuration
  • Verification scripts

Audience: DevOps, Infrastructure Time: 20 minutes (assuming accounts already exist)

4. Bootstrap Guide

Set up AWS OIDC provider and Terraform backend.

Covers:

  • S3 bucket for Terraform state
  • DynamoDB table for state locking
  • GitHub OIDC provider for authentication
  • IAM role for GitHub Actions
  • Bootstrap Terraform module (optional)

Audience: DevOps, Infrastructure Time: 15-20 minutes

For New Engineers

  1. Project Overview → 2. Initial Setup → 3. Testing Guide → 4. Contributing

For DevOps

  1. Pre-Deployment Checklist → 2. Bootstrap Guide → 3. Deployment Guide → 4. Monitoring

For Architects

  1. Project Overview → 2. System Architecture → 3. Cost Analysis → 4. Security

Next Steps

After completing setup:

Common Setup Issues

AWS Bedrock Access Denied

  • Problem: AccessDeniedException when trying to use Bedrock
  • Solution: Request model access in AWS Console → Bedrock → Model access
  • Details: Troubleshooting Guide

Bedrock Knowledge Base Sync Issues

  • Problem: Documents not appearing in search results
  • Solution: Trigger Knowledge Base sync and wait for indexing
  • Details: Troubleshooting Guide

GitHub Actions Permission Denied

  • Problem: AccessDenied in GitHub Actions workflow
  • Solution: Update IAM role permissions via bootstrap script
  • Details: Bootstrap Guide

Need help? See Troubleshooting Guide or open an issue.