Service Wiring Contract: eyevinn-intercom-manager

Source-verified: URL formats and field names verified against eyevinn/eyevinn-intercom-manager README and docker-entrypoint.sh.

Eyevinn Open Intercom Manager is a low-latency WebRTC intercom server. It requires two supporting services:

1. Symphony Media Bridge (eyevinn-docker-wrtc-sfu) — the WebRTC media relay
2. Database — MongoDB or CouchDB (both are supported)

Dependency Creation Order

Service	OSC service ID	Purpose
Symphony Media Bridge	eyevinn-docker-wrtc-sfu	WebRTC SFU for audio routing
MongoDB	birme-osc-mongodb	User/channel persistence
CouchDB	apache-couchdb	User/channel persistence (alternative to MongoDB)

1. Create the Symphony Media Bridge instance first
2. Create the database (MongoDB or CouchDB)
3. Create the Intercom Manager, wiring it to the SFU and database

Field Reference

smbUrl — Symphony Media Bridge URL

• Maps to internal env var: SMB_ADDRESS
• Format: Plain HTTP or HTTPS URL with port. No embedded credentials.
• Correct: http://my-smb.svc.prod.osaas.io:8080
• Wrong: http://user:[email protected] (credentials must NOT be embedded)
• Credentials for the SFU go in smbApiKey, not in the URL
• The SFU typically runs on port 8080

smbApiKey — Symphony Media Bridge API Key

• Maps to internal env var: SMB_APIKEY

• Format: Opaque API key string — the SFU's API key found in the SFU instance connection details

• Store in secrets and reference via {{secrets.SMB_API_KEY}} (recommended):

  create-service-secret intercom-name SMB_API_KEY <your-smb-api-key>
  

dbUrl — Database Connection URL

• Maps to internal env var: DB_CONNECTION_STRING
• CRITICAL: The URL MUST include the database name as a path suffix

MongoDB format

• Correct: mongodb://admin:[email protected]:27017/intercom-manager
• Wrong: mongodb://my-mongo.svc.prod.osaas.io:27017 (missing database name path)

CouchDB format

• Correct: http://admin:[email protected]:5984/intercom-manager
• Wrong: http://my-couchdb.svc.prod.osaas.io:5984 (missing /intercom-manager path)

Omitting the database name path segment causes the service to fail during DB initialization.

Store the full URL as a secret to protect the embedded password:

create-service-secret intercom-name DB_URL http://admin:mypassword@host:5984/intercom-manager

Then set dbUrl to {{secrets.DB_URL}}.

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-manager. The service parses the path segment as the database name and fails to initialize if it is absent.
3. Wrong protocol prefix: MongoDB uses mongodb://, CouchDB uses http:// or https://.

Common Errors

Error	Cause	Fix
Pod crashes on startup with DB init error	dbUrl missing database name path	Add /dbname suffix to dbUrl
SMB connection refused	smbUrl has embedded credentials or wrong port	Use plain URL with port 8080; credentials go in smbApiKey
DB_CONNECTION_STRING format error	Wrong protocol prefix	MongoDB uses mongodb://, CouchDB uses http:// or https://

Parameter Store Recommendation

Store smbApiKey, dbUrl (contains database 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 Symphony Media Bridge
create-service-instance service=eyevinn-docker-wrtc-sfu name=my-smb

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

# Step 3: Create MongoDB instance (or use apache-couchdb)
create-service-instance service=birme-osc-mongodb name=my-mongo

# Step 4: Create Intercom Manager — use PLAIN SFU URL with port, full DB URL with /dbname path
create-service-instance service=eyevinn-intercom-manager name=my-intercom \
  smbUrl=http://my-smb.svc.prod.osaas.io:8080 \
  smbApiKey=<key-from-sfu-details> \
  dbUrl=mongodb://admin:[email protected]:27017/intercom-manager

Notes

• OSC_ACCESS_TOKEN is optional — used for link sharing and reauthentication
• PUBLIC_HOST is set automatically by OSC via OSC_HOSTNAME environment variable
• The intercom web UI is served from the same port as the API (default 8000)
• See also: User-Guide:-Cloud-Intercom for end-user setup