Skip to content

Configuration

Detailed setup for your GCP project, Firebase, secrets, Firestore rules, and CI/CD.

1. Create and configure your GCP project

If you do not have a project yet, create one:

gcloud projects create your-gcp-project-id --name="ScamShield AI"
gcloud config set project your-gcp-project-id

Enable required APIs

gcloud services enable \
  cloudfunctions.googleapis.com \
  cloudbuild.googleapis.com \
  firestore.googleapis.com \
  cloudtasks.googleapis.com \
  secretmanager.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  --project=your-gcp-project-id

Create a Firestore database

ScamShield uses Firestore in Native mode:

gcloud firestore databases create \
  --location=asia-south1 \
  --project=your-gcp-project-id

Firestore mode is permanent

Once you create a Firestore database in Native mode, it cannot be switched to Datastore mode (or vice versa). Make sure you select Native mode.

2. Firebase setup

Initialize Firebase in the project

firebase login
firebase projects:list  # Verify your project appears
firebase use your-gcp-project-id

If this is a new project, initialize Firebase:

firebase init

Select these features when prompted:

  • Firestore -- for security rules and indexes
  • Functions -- Python runtime
  • Hosting -- for the API rewrite rule
  • Emulators -- for local development

The repository already includes firebase.json, firestore.rules, and firestore.indexes.json, so you can accept the existing files when prompted.

Already configured?

If you cloned the repo and the project already has a .firebaserc file, just run firebase use your-gcp-project-id to select your project.

3. Set secrets

ScamShield requires two secrets stored in Firebase/GCP Secret Manager:

GEMINI_API_KEY

Your Google Gemini API key for LLM calls:

firebase functions:secrets:set GEMINI_API_KEY --project=your-gcp-project-id
# Paste your Gemini API key when prompted

SCAMSHIELD_API_KEY

The API key that authenticates incoming requests to your endpoint. Generate one and set it:

# Generate a key
python -c "import secrets; print(f'scamshield-{secrets.token_hex(16)}')"

# Set it in Secret Manager
firebase functions:secrets:set SCAMSHIELD_API_KEY --project=your-gcp-project-id
# Paste the generated key when prompted

Keep your API key safe

Save the generated SCAMSHIELD_API_KEY somewhere secure. You will need it to authenticate requests to your endpoint and for the dashboard configuration.

Verify secrets

gcloud secrets list --project=your-gcp-project-id

You should see both GEMINI_API_KEY and SCAMSHIELD_API_KEY listed.

4. Local environment file

For local development and testing, create a .env.local file in the project root. Use .env.example as a template:

cp .env.example .env.local

Edit .env.local:

# Required: Google Gemini API Key
# Get from: https://aistudio.google.com/app/apikey
GEMINI_API_KEY=your-gemini-api-key-here

# Required: ScamShield API Key (for endpoint authentication)
# Must match the value you set in Secret Manager
SCAMSHIELD_API_KEY=scamshield-your-generated-key-here

# Optional: Firebase Project ID
# Only needed if deploying to Firebase from local machine
# FIREBASE_PROJECT_ID=your-gcp-project-id

.env.local is gitignored

This file is listed in .gitignore and will not be committed. Never commit secrets to the repository.

5. Firestore security rules

The repository includes firestore.rules that locks down all collections to Admin SDK access only (no client-side reads or writes). Deploy them:

firebase deploy --only firestore:rules --project=your-gcp-project-id

The rules enforce:

Collection Access
honeypot_sessions Admin SDK only (Cloud Functions)
evidence_index Admin SDK only (Cloud Functions)
reports Read: authenticated users / Write: Admin SDK only
Everything else Denied

6. Cloud Tasks queue (optional)

ScamShield uses Cloud Tasks for delayed callbacks -- sending the final intelligence report after a conversation ends. If you plan to use this feature, create the queue:

gcloud tasks queues create scamshield-callbacks \
  --location=asia-south1 \
  --project=your-gcp-project-id

Not needed for basic testing

The delayed callback feature is optional. The core scam detection and response generation work without Cloud Tasks.

7. Workload Identity Federation for CI/CD (optional)

If you want GitHub Actions to deploy automatically on push to main, set up keyless authentication using Workload Identity Federation. This eliminates the need for stored service account keys.

The repository includes a setup script:

chmod +x setup-wif.sh

Before running, edit the variables at the top of setup-wif.sh:

PROJECT_ID="your-gcp-project-id"
GITHUB_REPO="your-github-org/scamshield-ai"  # your GitHub org/repo
GITHUB_OWNER="your-github-org"                 # your GitHub org or username

Then run:

./setup-wif.sh

The script will:

  1. Enable IAM and STS APIs
  2. Create a service account with required roles
  3. Create a Workload Identity Pool and OIDC Provider
  4. Bind the pool to your service account (restricted to your GitHub org)

After running, update .github/workflows/deploy.yml with the values printed by the script:

  • workload_identity_provider -- the full provider resource name
  • service_account -- the service account email

One-time setup

You only need to run this once per GCP project. The WIF configuration persists across deployments.

Configuration checklist

Before moving on, verify:

  • [ ] GCP project created with billing enabled
  • [ ] Required APIs enabled
  • [ ] Firestore database created in Native mode (asia-south1)
  • [ ] Firebase CLI linked to your project (firebase use your-gcp-project-id)
  • [ ] GEMINI_API_KEY set in Secret Manager
  • [ ] SCAMSHIELD_API_KEY set in Secret Manager
  • [ ] .env.local created with both keys
  • [ ] Firestore security rules deployed
  • [ ] (Optional) Cloud Tasks queue created
  • [ ] (Optional) WIF configured for CI/CD

Next steps