Release identity and service compatibility
Use this reference before you choose a release, replace a component or roll back an upgrade. Deploy the approved component and configuration set for your deployment. A shared tag, an unchanged component or a service-change table alone does not prove that a mixed set works together.
Availability: Operators need the target release notes, the generated deployment bundle, registry access and the release's schema and upgrade instructions. SDK versions and the separately managed Portal have their own release identities. Confirm support coverage with your support agreement; a shared version label does not establish tested compatibility.
Keep four identities separate
| Identity | What it tells you | What it does not establish |
|---|---|---|
| Product release/tag | Which product revision and release instructions are intended | That a specific host runs its images or has applied its configuration |
| Deployment manifest and bundle reference | Which roles, images and generated files are selected for that environment/features | That the target hosts fetched them or passed acceptance |
| Actual image/configuration identity | What content was delivered and is running | Compatibility with every other service, schema or client |
| Test/acceptance evidence | Which concrete combination and scenario worked | Arbitrary later image tags, different feature sets or untested workloads |
The Portal's release distribution manifest selects deployment registries and Delphi image names. Upstream images, mounted binaries and externally managed services also belong in your deployment inventory. The distribution list is neither the complete running-container catalogue nor a test result.
Capture a useful release record
Before and after a change, record:
- Deployment and namespace; product release; release notes and migration instructions.
- Each affected service's image reference, registry digest and running image identity; platform/architecture when relevant.
- Configuration bundle reference and recoverable exact content/version; effective feature profile and required configuration/secret version identifiers, without their values.
- Schema/migration state, independently versioned SDK/client contracts and external dependency versions needed for the scenario.
- The acceptance checks, result and time, plus the previous compatible recovery set.
On a known API host, a bounded identity check is:
docker inspect --format '{{.Name}} {{.Config.Image}} {{.Image}}' voiceai-telapi
This prints the container's reference and image ID, not its environment. A local image ID is not interchangeable with a registry manifest digest, so keep the distribution/registry record as well. The normal refresh helper compares running container IDs with local image metadata. It detects stale local instances; it is not a provenance or interoperability test.
Tags are not immutable content
Service Compose uses the configured Delphi release tag and upstream references such as postgres:17-alpine, redis:7-alpine, caddy:2-alpine and ubuntu/squid:latest. These names can resolve to different content over time. Record resolved digests when reproducibility matters. Several Delphi base images are pinned by digest from 0.9.18; the Compose service images above are not.
Decide whether a component can move alone
| Proposed change | Evidence needed before applying it |
|---|---|
| Restart/recreate unchanged component | Recorded image/configuration identity, dependency health and the same intended schema/credentials |
| Apply a documented component patch | Exact patch scope, permitted dependency set, migration/activation order, targeted acceptance and rollback instructions |
| Mix a newer component with older dependencies | Explicit evidence for that combination; otherwise use the approved coordinated release set |
| Roll back after a migration | Confirm old images can use the resulting schema, or use the planned schema/data recovery procedure; merely retagging images is insufficient |
| Change optional modules/topology | Generated manifest and effective flags, additional dependencies/network paths, entitlement and feature-specific verification |
Mixed-release compatibility: this handbook lists no accepted mixed-release combination. Upgrade the complete release set unless the release notes for a documented patch name the permitted dependency set. To add a combination, deploy it in a test environment, run the checks in apply and accept the selected set, and keep the image digests and results.
A service-change table says which components changed. It does not certify unchanged components against new schemas, queue payloads or runtime contracts.
Release register
The register lists release references for upgrade planning. It does not assign support status or establish that a release is deployed. Confirm the selected release, its published artifacts and your support agreement before an upgrade.
| Release line | Latest patch | Release month |
|---|---|---|
| v0.9.18 | v0.9.18 | October 2026 |
| v0.9.17 | v0.9.17-patch2 | September 2026 |
| v0.9.16 | v0.9.16-patch2 | July 2026 |
| v0.9.15 | v0.9.15-patch4 | July 2026 |
| v0.9.14 | v0.9.14-patch3 | June 2026 |
| v0.9.13 | v0.9.13-patch3 | June 2026 |
| v0.9.12 | v0.9.12-patch1 | May 2026 |
| v0.9.11 | None | May 2026 |
| v0.9.10 | v0.9.10-patch1 | April 2026 |
Upgrade to 0.9.18
Read the 0.9.18 release notes before you start. The following steps are mandatory for an upgrade from 0.9.17:
- Upgrade the full 0.9.18 release set. Do not mix in 0.9.17 components without acceptance evidence for that exact combination.
- Run the database migrations with the Ops
db-migrateservice, including the newlive_session_usagemigration, before the new API, Web and Voice services start. - Set
FEATURE_BROWSER_SDKandFEATURE_WEBRTCexplicitly totrueorfalse. Unset flags are off. TelAPI and TelWeb reject a supplied value other than literaltrueorfalse; they also reject WebRTC enabled without the Browser SDK. - Remove the retired
FEATURE_API_ACCESS; it has no alias. BecauseFEATURE_API_ACCESSwas on by default in 0.9.17, the Browser SDK stays off unless you enable it. Follow upgrade the integration capabilities. - If your teams use the system-audio library, configure its storage first. Without it, uploads fail with "System audio storage is not configured". See choose a storage backend.
Verify the upgrade with apply and accept the selected set. Feature availability lists which services need each flag.
Service image changes by release
Each row lists the Delphi images whose digest changed against the preceding release. The table stores changed/not-changed labels only, not digests or test results, so it cannot reconstruct an immutable deployment. An omitted component means "not changed", not "tested against every other component". Missing patch rows are unknown; do not interpolate them.
| Release | Images that changed |
|---|---|
| v0.9.18 | TelPro, RTPEngine, WebRTC (Janus), TelSys, TelPhi, AudioProc, TelAPI, TelWeb, Media server, Scaler, Tasker, DB migrate, Log-to-span |
| v0.9.17-patch2 | TelPro, TelPhi, TelAPI, TelWeb, Tasker, DB migrate, Scaler |
| v0.9.17-patch1 | TelPro, RTPEngine, WebRTC (Janus), TelSys, TelPhi, AudioProc, TelAPI, TelWeb, Media server, Scaler, Tasker, DB migrate, Log-to-span |
| v0.9.17 | TelPro, TelSys, TelPhi, AudioProc, TelAPI, TelWeb, Media server, Scaler, Tasker, DB migrate, Log-to-span |
| v0.9.16-patch1 | TelPro, RTPEngine, TelPhi, TelAPI, TelWeb, Scaler, Log-to-span |
| v0.9.16 | TelPro, RTPEngine, WebRTC (Janus), TelSys, TelPhi, AudioProc, TelAPI, TelWeb, Media server, Scaler, Tasker, DB migrate, Log-to-span |
| v0.9.15 | TelPro, RTPEngine, WebRTC (Janus), TelSys, TelPhi, AudioProc, TelAPI, TelWeb, Media server, Scaler, Tasker, DB migrate, Log-to-span |
| v0.9.14-patch3 | TelPro, RTPEngine, WebRTC (Janus), TelPhi, AudioProc, TelAPI, TelWeb, Scaler, Tasker, DB migrate, Log-to-span |
| v0.9.14-patch1 | TelPhi, TelAPI, TelWeb, DB migrate |
| v0.9.14 | TelPro, RTPEngine, WebRTC (Janus), TelSys, TelPhi, AudioProc, TelAPI, TelWeb, Media server, Scaler, Tasker, DB migrate |
| v0.9.13-patch3 | TelAPI, TelWeb, TelPro, TelPhi, Tasker, DB migrate |
| v0.9.13-patch1 | TelPro, TelPhi, TelWeb, TelAPI, DB migrate |
| v0.9.13 | TelPro, TelSys, TelPhi, TelAPI, TelWeb, Scaler, Tasker, DB migrate, Log-to-span |
| v0.9.12-patch1 | TelPhi |
| v0.9.12 | TelPhi, TelAPI, TelWeb, Media server, Scaler, Tasker |
| v0.9.11 | TelPro, TelSys, TelPhi, TelAPI, TelWeb, Media server, Scaler, Tasker |
The Media server image contains the media-upload service. The voiceai-log-to-span image is used by the local development topology. Voice and TelPro hosts run the same converter as a mounted binary in an alpine:3.19 sidecar, so a Log-to-span change also needs that binary updated. Relay uses the upstream coturn image below; there is no Delphi voiceai-turn image. The SDK keeps its own version and release process; these rows are not an SDK support matrix. See browser integration for the separately versioned SDK reference.
Upgrade the separately managed Portal
Availability: this procedure is for operators responsible for the Portal deployment. A Delphi customer deployment upgrade does not itself upgrade the Portal.
- Back up the Portal database and record the Portal image and migration state before its separate rollout. Confirm that the backup can be restored.
- Apply the Portal release's database migrations before starting its new application version. These migrations include table rebuilds and removal of obsolete module-grant storage; they are not purely additive. Account session-version changes can require users to sign in again.
- Verify Portal sign-in, customer memberships and feature-profile selection after the migration. Keep the prior image and database backup together for recovery. Replacing the container alone does not reverse a database migration.
Declared upstream versions
These are the upstream versions declared in the product source for release 0.9.18. They are declarations and defaults, not a bill of materials read from running images: build arguments, deployment overrides and mutable tags can change delivered content, so record resolved digests and effective overrides separately.
| Component | Declared version or image | Declaration location |
|---|---|---|
| Kamailio / TelPro | 6.1.4 source build | .docker/voiceai-telpro/Dockerfile: KAMAILIO_VERSION |
| hiredis / TelPro | v1.4.1 source build | .docker/voiceai-telpro/Dockerfile: HIREDIS_VERSION |
| RTPEngine | Repository channel 26.0, packages 26.0.1.24-1~bpo13+1 | .docker/voiceai-rtpengine/Dockerfile: RTPENGINE_VERSION, RTPENGINE_PACKAGE_VERSION |
| Asterisk / TelSys | 22.11.0, source archive verified with a SHA-256 checksum | .docker/voiceai-telsys/Dockerfile: ASTERISK_VER, ASTERISK_SHA256 |
| Janus / browser gateway | v1.4.1 Git tag | .docker/voiceai-webrtc/Dockerfile: JANUS_VERSION |
| Silero VAD model / AudioProc | v5.1.2 | .docker/voiceai-audioproc/Dockerfile: SILERO_VAD_VERSION |
| Node.js / application and migration images | node:24.21.0-alpine3.24, pinned by digest | .docker/voiceai-{telapi,telweb,telphi,tasker,scaler,db-migrate}/Dockerfile |
| Debian / TelPro, TelSys, RTPEngine and Janus | debian:trixie-slim, pinned by digest | Their .docker/voiceai-*/Dockerfile files; also the AudioProc zlib-builder build stage |
| Go / media-upload, Log-to-span, TelSys tool | golang:1.27.1-alpine3.24, pinned by digest; build stage only | .docker/voiceai-media-server/Dockerfile, apps/log-to-span/Dockerfile, TelSys Dockerfile |
| Alpine / media-upload and Log-to-span images | alpine:3.24.2, pinned by digest | .docker/voiceai-media-server/Dockerfile, apps/log-to-span/Dockerfile |
| Alpine / Log-to-span sidecars | alpine:3.19 | .infrastructure/services/voice/docker-compose.yaml and telpro/docker-compose.yml |
| CPU AudioProc | python:3.11-slim-trixie, pinned by digest | .docker/voiceai-audioproc/Dockerfile |
| GPU AudioProc | nvidia/cuda:12.4.1-runtime-ubuntu22.04 | Same AudioProc Dockerfile; the DEVICE build argument selects the stage |
| coturn / relay | coturn/coturn:4.6.2 | .infrastructure/services/telpro/docker-compose.yml |
| PostgreSQL | postgres:17-alpine | .infrastructure/services/database/docker-compose.yaml |
| PgBouncer | edoburu/pgbouncer:v1.25.1-p0 | Database Compose |
| Redis | redis:7-alpine | Database Compose |
| Caddy / Web and Media | caddy:2-alpine | .infrastructure/services/web/docker-compose.yaml and media/docker-compose.yaml |
| Host operating system | ubuntu-22.04 cloud image | .infrastructure/terraform/modules/server/main.tf: image |
| Squid | ubuntu/squid:latest | .infrastructure/services/squid/docker-compose.yaml |
| OpenTelemetry collector (contrib) | otel/opentelemetry-collector-contrib:0.159.0 | API, Database, Ops, Squid, TelPro, Voice and Web Compose; signoz/docker-compose.export-collector.yaml |
| SigNoz application | signoz/signoz:v0.139.0 default | .infrastructure/services/signoz/vars.yaml and render-casting.sh: SIGNOZ_VERSION |
| SigNoz ingester collector | signoz/signoz-otel-collector:v0.142.0 default | signoz/render-casting.sh; SIGNOZ_OTELCOL_TAG overrides it |
| ClickHouse | clickhouse/clickhouse-server:25.5.6 default | signoz/vars.yaml and render-casting.sh: CLICKHOUSE_IMAGE |
| Keycloak / Portal identity | quay.io/keycloak/keycloak:26.7.4, pinned by digest | apps/portal/identity/Dockerfile; part of the separately managed Portal |
| Node.js / Portal | node:22-alpine | apps/portal/Dockerfile; part of the separately managed Portal |
Defaults, overrides and mutable references
ECR_REGISTRY and ECR_TAG select the Delphi images in the generated service Compose files. Several production declarations fall back to latest; development uses dev. A fallback is not a recommended release selection. Verify the effective generated deployment and keep its identities.
Squid is not the only mutable reference. Major/minor image tags and even version-looking tags can be replaced, and repository channels can gain new packages. Use the declarations to investigate, then keep the actual build and running identities.
SigNoz's application, ingester collector, contrib export collector and ClickHouse have separate version controls. Do not set the ingester to the application version merely to make them match. Inspect the rendered casting and the effective deployment overrides before you apply its upgrade procedure. Telemetry and monitoring explains the collector and ingester roles; service health covers controlled activation.
Review the dependency boundaries
| Component set | What can couple its upgrade to other components |
|---|---|
| TelWeb | Database/auth model, role/session rules, API contracts and background notification jobs |
| TelAPI | Database/Redis schema and state, browser SDK/session protocols, callbacks, Voice and provider/media behavior |
| TelPhi + TelSys + optional AudioProc | ARI/media interfaces, provider audio, edge signaling, recording/job contracts; treat the bundle as coordinated unless the patch documents otherwise |
| TelPro signaling/media/gateway | Voice routing/media, generated trunk/TLS policy, Redis state and enabled browser gateway/relay behavior |
| Ops | Migration schema, job payload producers/consumers, cloud operations, backups and notification transport |
| Database/Redis | Every consumer's credentials, TLS, schema/state and recovery compatibility |
| Media/telemetry/proxy | Consumer authentication/trust, data formats, persistent storage, export paths and external connectivity |
For browser clients, keep the SDK's independent version and verify its supported session modes and contracts with the browser integration guide. Do not assign the platform tag to the SDK to make a table look aligned.
Apply and accept the selected set
Follow the deployment journey: preserve the recovery point, preview the intended update, run required migrations and activation in the release's order, and verify each affected role. A finished release distribution is not evidence that your installation completed this step.
Use service health plus the applicable end-to-end scenario: sign-in and team access, phone or browser conversation, callback, recording or backup job, or feature activation. Store the result with the identities above. A failed scoped check is a failed release criterion for that change; do not replace it with an unrelated green build.
If acceptance fails, find the failed layer before rollback. Configuration recovery separates application snapshots, bundle/secret versions, database recovery and external objects. Verify again after rollback and keep the failed combination on record rather than marking it compatible.
Related
- Deploy, verify and update Delphi: to apply the selected release set in the right order.
- Environment variable reference: to review variables added or removed in this release.
- Choose and verify a configuration recovery: to roll back a release that fails acceptance.
- Service topology: to see which role runs each listed image.