Skip to content

Deployment Services Setup

This document describes how to configure external service integrations for a new cbapp tenant deployment.

Overview

cbapp integrates with several external services that require API keys:

Service Env Variable Purpose
YASP YASP_API_KEY Survey management
CBFiles FILES_API_KEY, FILES_TENANT_BUCKET File storage
Anthropic ANTHROPIC_API_KEY AI chat features
i360 N/A (data is loaded, not API) Voter data

Quick Setup

Run the setup script to configure all services for a new tenant:

# From the cbapp directory
python scripts/setup_services.py --tenant-id mytenantname

# Or with all options
python scripts/setup_services.py \
    --tenant-id mytenantname \
    --yasp-base-url https://surveys.nominate.ai/api/v1 \
    --files-base-url https://files.nominate.ai/api/v1 \
    --anthropic-key sk-ant-xxx

The script will: 1. Generate a YASP API key for the tenant 2. Create a CBFiles bucket and API key 3. Validate Anthropic API key (if provided) 4. Update the .env file with all required values 5. Run validation to confirm services are accessible

Manual Setup

1. YASP Survey Platform

YASP manages surveys for field work. Each tenant needs its own API key.

Generate YASP API Key: 

# On the YASP server (surveys.nominate.ai)
cd /path/to/yasp
python -c "import secrets; print(f'yasp_{secrets.token_urlsafe(32)}')"

Add to tenant database (YASP admin): 

INSERT INTO api_keys (key, tenant_id, created_at)
VALUES ('yasp_xxx', 'mytenantname', NOW());

Configure in .env: 

YASP_BASE_URL=https://surveys.nominate.ai/api/v1
YASP_API_KEY=yasp_xxx

2. CBFiles Storage Service

CBFiles provides file storage for imports, exports, and user files.

Bootstrap tenant bucket: 

# On the CBFiles server (files.nominate.ai)
cd /path/to/cbfiles

# Create API key for tenant
python -c "import secrets; print(f'cbfiles_{secrets.token_urlsafe(32)}')"

Add to CBFiles database: 

-- Create tenant bucket
INSERT INTO buckets (name, access, created_at)
VALUES ('mytenantname', 'private', NOW());

-- Create API key
INSERT INTO api_keys (key, bucket_id, created_at)
SELECT 'cbfiles_xxx', id, NOW() FROM buckets WHERE name = 'mytenantname';

Configure in .env: 

FILES_BASE_URL=https://files.nominate.ai/api/v1
FILES_API_KEY=cbfiles_xxx
FILES_TENANT_BUCKET=mytenantname

3. Anthropic API (AI Chat)

AI chat features require an Anthropic API key. This is typically a shared key.

Get API key: 1. Go to https://console.anthropic.com/ 2. Generate or copy existing API key

Configure in .env: 

ANTHROPIC_API_KEY=sk-ant-xxx
CB_CHAT_MODEL=claude-sonnet-4-20250514

4. Service-to-Service Auth

For tenant manager to call cbapp API:

# Generate API key
python -c "import secrets; print(secrets.token_hex(16))"

Configure in .env: 

API_KEYS=generated_key_here

Validation

After configuration, validate services are working:

# Run the validation script
python scripts/validate_services.py

# Or check individual services
python scripts/validate_services.py --service yasp
python scripts/validate_services.py --service files
python scripts/validate_services.py --service anthropic

Expected output: 

Service Validation Results
==========================
[OK] YASP: Connected, 0 surveys found
[OK] CBFiles: Connected, bucket 'mytenantname' accessible
[OK] Anthropic: API key valid
[OK] Database: Connected, schema version 1.0.0

All services configured correctly.

Troubleshooting

YASP Connection Failed

Error: 401 Unauthorized
- Verify YASP_API_KEY is correct - Check if key exists in YASP database - Ensure YASP service is running

CBFiles Bucket Not Found

Error: 404 Bucket not found
- Create bucket in CBFiles database - Verify FILES_TENANT_BUCKET matches bucket name - Check FILES_API_KEY has access to bucket

Anthropic API Error

Error: Invalid API key
- Verify ANTHROPIC_API_KEY is correct - Check API key hasn't been revoked - Ensure sufficient API credits

Deployment Checklist

Before deploying a new tenant:

  • Generate YASP API key and add to YASP database
  • Create CBFiles bucket and API key
  • Configure Anthropic API key (or use shared key)
  • Generate service-to-service API key
  • Update .env with all keys
  • Run python scripts/validate_services.py
  • Run e2e tests: pytest tests/e2e/ -v
  • .env.example - Template with all required variables
  • src/api/services/yasp_service.py - YASP integration
  • src/api/services/files_service.py - CBFiles integration
  • src/api/routes/cb_chat.py - Anthropic integration
  • scripts/setup_services.py - Automated setup script
  • scripts/validate_services.py - Service validation script