Skip to content

Service: Intercom Manager Wiring Contract

Jump to bottom
Claude edited this page Jun 20, 2026 · 2 revisions

Service Wiring Contract: eyevinn-intercom-manager

Eyevinn Open Intercom Manager requires three dependencies created in order: SFU (Symphony Media Bridge) → CouchDB → Intercom Manager.

Dependency Creation Order

  1. Create SFU: eyevinn-docker-wrtc-sfu (or your own SFU deployment)
  2. Create CouchDB: apache-couchdb
  3. Create Intercom Manager: eyevinn-intercom-manager

Field Reference

smbUrl — SFU HTTP endpoint

  • Format: Plain HTTP/HTTPS URL, no embedded credentials, no query parameters
  • Correct: https://xxxx.svc.prod.osaas.io
  • Wrong: https://user:password@xxxx.svc.prod.osaas.io (credentials must NOT be embedded)
  • Credentials belong in smbApiKey, not in this URL

smbApiKey — SFU API key

  • Format: Plain string (the SFU's API key)
  • Stored separately from smbUrl to keep credentials out of the URL field
  • Find this in the SFU instance's connection details

dbUrl — CouchDB connection string

  • Format: Full CouchDB URL including the target database name in the path
  • Correct: http://admin:password@xxxx.svc.prod.osaas.io/intercom
  • Wrong: http://admin:password@xxxx.svc.prod.osaas.io (missing /intercom path — service crashes on startup)
  • The database name (intercom) is the last path segment — omitting it causes DB initialization failure
  • Credentials (admin/password) ARE embedded in this URL (CouchDB standard format)
  • Also supports MongoDB: mongodb://user:password@host/intercom

whipAuthKey — WHIP endpoint auth key (optional)

  • Secret key for authenticating WHIP producers
  • Store in parameter store if sensitive

Common Mistakes

  1. Credentials in smbUrl: Putting API credentials in the SFU URL instead of smbApiKey. The SFU expects the API key as an HTTP header, not URL auth.
  2. Missing database path in dbUrl: Using just http://host instead of http://host/intercom. The service parses the path segment as the database name and fails to initialize if it is absent.

Parameter Store Recommendation

Store smbApiKey, dbUrl (contains CouchDB password), and whipAuthKey as secrets via setup-parameter-store + set-parameter. Pass the parameter store name as configService when creating the Intercom instance.

Example Creation Flow

# Step 1: Create SFU
create-service-instance service=eyevinn-docker-wrtc-sfu name=my-sfu

# Step 2: Get SFU endpoint and API key from instance details
get-instance-status service=eyevinn-docker-wrtc-sfu name=my-sfu

# Step 3: Create CouchDB
create-service-instance service=apache-couchdb name=my-couchdb

# Step 4: Create Intercom — use PLAIN SFU URL (no auth), full CouchDB URL with /intercom path
create-service-instance service=eyevinn-intercom-manager name=my-intercom \
  smbUrl=https://my-sfu.svc.prod.osaas.io \
  smbApiKey=<key-from-sfu-details> \
  dbUrl=http://admin:password@my-couchdb.svc.prod.osaas.io/intercom

Clone this wiki locally