Skip to main content

Shared Knowledge Base Setup Guide

Quick Start​

The Knowledge Base is now configured to use a shared Firestore (toto-bo) so all environments access the same KB entries.

Setup Steps​

1. Create/Update Firebase Secret in Secret Manager​

In Google Cloud Console:

  1. Go to toto-bo Firebase project
  2. IAM & Admin → Service Accounts
  3. Create a service account for toto-ai-hub (or use existing)
  4. Grant roles:
    • Cloud Datastore User (for Firestore read/write)
  5. Create key (JSON) and download
  6. Store in Google Secret Manager:
    • Secret name: toto-bo-service-account
    • Value: Entire JSON content as a single-line string (no formatting)
    • Project: toto-ai-hub (or the project where toto-ai-hub is deployed)

Important: The entire JSON must be stored as a single string. When copying the JSON:

  • Remove all line breaks
  • Keep it as one continuous string
  • Or use a tool to minify the JSON

Example:

{"type":"service_account","project_id":"toto-bo","private_key_id":"...","private_key":"-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n","client_email":"...","client_id":"...","auth_uri":"...","token_uri":"...","auth_provider_x509_cert_url":"...","client_x509_cert_url":"..."}

2. Update apphosting.yaml​

Already done! The apphosting.yaml now includes:

env:
  - variable: TOTO_BO_SERVICE_ACCOUNT_KEY
    secret: toto-bo-service-account
    availability:
      - BUILD
      - RUNTIME

3. Migrate Existing KB Entries​

If you have existing KB entries in toto-f9d2f-stg, migrate them to the shared location:

cd toto-ai-hub
npx ts-node scripts/migrate-knowledge-base.ts toto-bo

This will:

  • Copy all hardcoded entries to toto-bo Firestore
  • Preserve existing entries if they exist
  • Update entries with latest content

4. Deploy​

After migration, deploy toto-ai-hub:

git add .
git commit -m "Implement shared KB architecture"
git push origin main

Firebase App Hosting will automatically deploy.

5. Verify​

After deployment, check logs:

# Should see:
✅ Using toto-bo service account from environment variable
✅ Firebase Admin SDK initialized for toto-bo (shared KB access)
📚 Using shared KB Firestore (toto-bo) for cross-environment access
✅ Loaded X knowledge base entries from Firestore

Test API:

curl https://toto-ai-hub-backend--toto-ai-hub.us-central1.hosted.app/api/ai/knowledge

Local Development​

Set TOTO_BO_SERVICE_ACCOUNT_KEY environment variable in your local .env file:

TOTO_BO_SERVICE_ACCOUNT_KEY='{"type":"service_account","project_id":"toto-bo",...}'

Troubleshooting​

"Shared KB will not be available" warning​

  • Verify TOTO_BO_SERVICE_ACCOUNT_KEY environment variable is set
  • Check secret exists in Secret Manager
  • Verify service account has Firestore permissions

Empty KB after migration​

  • Check Firebase Console → toto-bo → Firestore
  • Verify knowledge_base collection exists
  • Re-run migration script if needed

Manual Secret Setup​

If you need to manually set up the secret (see Shared KB Setup for automated setup):

Prerequisites​

  1. Ensure you're authenticated with gcloud: gcloud auth login
  2. Set the project: gcloud config set project toto-ai-hub

Create the Secret​

# Navigate to toto-ai-hub directory
cd C:\Users\tcost\VS\toto\toto-ai-hub

# Read and minify the service account JSON
$serviceAccountJson = Get-Content "..\toto-bo\toto-bo-firebase-adminsdk-fbsvc-138f229598.json" -Raw | ConvertFrom-Json | ConvertTo-Json -Compress

# Create the secret
echo $serviceAccountJson | gcloud secrets create toto-bo-service-account --data-file=- --project=toto-ai-hub

If the secret already exists and you want to update it:

echo $serviceAccountJson | gcloud secrets versions add toto-bo-service-account --data-file=- --project=toto-ai-hub

Grant Access to App Hosting​

firebase apphosting:secrets:grantaccess toto-bo-service-account --backend toto-ai-hub-backend --project toto-ai-hub