Skip to main content
Version: Next — unreleased

Prerequisites for a Delphi deployment

Use this page to prepare everything that provisioning expects to exist. The reference topology runs each role on its own Linux host with Docker, connected by a private network.

Availability: These prerequisites apply to the reference topology from 0.9.18. No feature flag gates them. Optional parts, such as two-edge TelPro operation (TELPRO_HA_ENABLED), add the items marked on this page. When the list is complete, continue with Provision instances and bootstrap a role.

Hosts and roles​

Each role is one host type with its own configuration bundle. Service topology describes what each service does; this table shows what you need to plan for each host.

RoleMain servicesPublic addressInternet access
WebTelWeb behind CaddyYesDirect
APITelAPI behind an HTTPS load balancerNoThrough the Squid proxy
VoiceTelSys, TelPhi, AudioProcNoThrough the Squid proxy
OpsScaler, Tasker, one-shot database migrationNoThrough the Squid proxy
MediaMedia server behind CaddyNoThrough the Squid proxy
TelProKamailio, RTPEngine, Janus, coturnYesDirect
DatabasePostgreSQL, PgBouncer, RedisNoThrough the Squid proxy
SigNozTelemetry storage, dashboards and alertsNoThrough the Squid proxy
SquidOutbound HTTP proxy for private hostsYesDirect
BastionSSH entry point to every other hostYesDirect

Web, API, Voice, Ops, TelPro, Database and Squid also run a local telemetry collector that exports to SigNoz over the private network.

Host operating system​

  • Use the Ubuntu server image that your release supports. Release compatibility lists the supported upstream versions.
  • Provisioning installs Docker Engine with the Compose plugin from Docker's package repository, the AWS command-line tools and yq. You do not install them by hand.
  • Attach a separate data volume to the Database, Media and SigNoz hosts. Provisioning formats a new volume once and mounts it on every boot.
  • For capacity, size each host from the measurements in Plan ready capacity.

For the reference SIP TLS suite names, see Supported SIP TLS cipher suites. HTTPS terminators have a separate TLS policy.

Network ports​

Allow these inbound ports. Rows with the source "Private network" must be reachable only inside the private network. Outbound traffic is unrestricted at the firewall; the proxy controls where private hosts can go.

RolePort or rangeProtocolPurposeSource
Web80, 443TCPTelWeb and the optional SigNoz UI over HTTPSUsers
API load balancer443TCPPublic TelAPI; forwards to TELAPI_PORT (default 3001)API clients
TelProSIP_PORT (default 5060)UDP, TCPSIP from carriers and trunksCarriers
TelProSIPS_PORT (default 5061)TCPSIP over TLSCarriers
TelProJANUS_WS_PORT (default 443)TCPJanus browser WebSocketBrowsers
TelProTURN_PORT, TURN_TLS_PORT (3478, 5349)UDP, TCPTURN for browser voiceBrowsers
TelProRTP_PORT_MIN–RTP_PORT_MAX (20000–40000)UDPRTPEngine media for carrier callsCarriers
TelProJANUS_RTP_PORT_MIN–JANUS_RTP_PORT_MAX (10000–12000)UDPJanus media for browser callsBrowsers
TelProTURN_MIN_PORT–TURN_MAX_PORT (49152–51152)UDPTURN relayBrowsers
DatabasePOSTGRES_PORT, REDIS_PORTTCPDatabase and RedisPrivate network
Media443TCPMedia uploads and playbackPrivate network
SigNoz4317, 4318TCPTelemetry from the collectorsPrivate network
SigNozQuery API port (default 8080)TCPDebug views and stored SIP ladders and span treesWeb and Ops hosts, directly
Squid3128TCPOutbound proxyPrivate network
All22TCPSSH from the bastionBastion or private network

Web and Ops (Tasker) connect to the SigNoz query API directly, not through the outbound proxy. If Ops cannot reach it, the SIP ladder and span tree are not stored with the conversation; see Verify SIP ladder and span tree persistence.

The reference firewall reads the TelPro, Database and API port values from the parameter store at provisioning time. Seed those parameters first, as described in Before you provision.

Voice has no public address. It receives SIP and media from TelPro over the private network on SIP_PORT_INTERNAL and the TelSys RTP range RTPSTART–RTPEND.

Outbound access​

Private hosts reach the internet only through Squid. Provisioning writes the proxy settings for them and sets NO_PROXY to local and private addresses.

  • Squid accepts clients from the private subnet only.
  • It allows tunnels to port 443, to SSH on port 22 and to mail submission on ports 25, 465 and 587.
  • Allow the private hosts to reach your container registry, configuration bucket, parameter store, secrets store and any AI, speech or telephony providers your flows use.
  • On the SigNoz host, SIGNOZ_TRANSPARENT_PROXY_PORTS lists the outbound ports sent through the proxy, including the mail ports for alert email.

Web, TelPro, Squid and Bastion reach the internet directly. TelPro also needs outbound UDP to your carriers' media addresses.

Registry and cloud access​

The reference deployment uses two cloud providers. Prepare both before provisioning.

NeedUsed for
Container registryEvery role pulls its images from ECR_REGISTRY with the tag in ECR_TAG.
Configuration bucketEach host downloads its role bundle from CONFIG_BUCKET.
Parameter storeNon-secret values under your deployment namespace, shared or per role.
Secrets storeSecret values under your deployment namespace, per role.
Cloud access key per hostLets the host log in to the registry and read the bucket, parameters and secrets.
Server cloud project tokenCreates hosts, networks, firewalls and the load balancer; Ops uses it for scaling and DNS-based certificate renewal.
SSH key pair for the bastionThe bastion uses it to reach every host; Ops adds its public key to new servers.

Verify the host's AWS permissions​

Give each host access to the resources it actually consumes. The configuration reader needs s3:ListBucket on the configuration bucket and s3:GetObject on its selected role and shared bundle prefixes. Parameter resolution needs ssm:GetParametersByPath for the deployment's shared and service paths. Secret resolution needs secretsmanager:GetSecretValue for its selected secrets. Encrypted parameters, secrets or objects can also require decrypt access to their customer-managed key.

Registry login requires ecr:GetAuthorizationToken; image pulls also need repository-scoped download permissions. Keep permission to write deployment configuration or push images separate from the host's read access. Use the configured registry and region when checking access.

  1. Identify the AWS identity used by host initialization and by each application container. They can differ. Confirm the identity and resource scope without printing credential values or secret payloads.
  2. Verify configuration-bundle download, parameter and secret resolution, and image pull through the normal initialization workflow. An identity lookup alone does not verify those permissions.
  3. If an operation is denied, correct the specific action and resource scope, including any key policy, then repeat that operation. Do not replace a narrowly scoped host policy with administrator access.

For Tasker mail permissions and delivery verification, use SES prerequisites.

Diagnose an EC2 instance-profile connection​

Availability: this check applies only to applications running on Amazon EC2 with an attached instance role. Hosts on another cloud do not acquire EC2 credentials by setting an instance-profile flag.

  1. Check the container's credential selection. Delphi's instance-profile mode uses the AWS SDK default credential chain; it does not force the chain to select EC2. Remove unintended static credential overrides when the instance role is the intended identity, preserving the previous configuration for recovery.
  2. Confirm that the EC2 metadata endpoint is enabled and that the container can reach it directly. If the application uses an HTTP proxy, exclude the metadata address from that proxy using its effective bypass configuration.
  3. For a bridged container that cannot obtain an IMDSv2 token response, check the instance's metadata response hop limit. AWS recommends a hop limit of 2 for container environments; keep IMDSv2 token authentication required. Apply that change through the instance's infrastructure configuration and verify from the container. See AWS metadata options.
  4. Verify the resulting identity and repeat the intended AWS operation from the application context. Successful metadata access is not permission to read a secret, pull an image or send mail.

For two-edge TelPro operation, also provide HCLOUD_TOKEN to the TelPro hosts so that they can move the floating addresses. See Operate the telephony edge.

For the order in which parameters and secrets override each other, see Place configuration in the correct layer.

DNS names and certificates​

Create these DNS records before the first start. Use names under your own domain, for example app.example.com.

  • TelWeb name (DOMAIN_TELWEB): points to the Web host's public address. Caddy on the Web host requests its certificate automatically, so the name must resolve first.
  • SigNoz UI name (DOMAIN_SIGNOZ, optional): points to the Web host's public address. Caddy requests its certificate the same way.
  • API name (DOMAIN_API): points to the API load balancer, which holds a managed certificate for it.
  • TelPro edge name (DOMAIN_TELPRO): points to the TelPro public or SIP floating address. It needs the edge certificate for SIP over TLS, Janus and TURN, which Ops renews.

The shared variables reference defines these names. The edge certificate, database TLS and Redis TLS have their own settings and activation steps. Prepare them with Verify platform TLS.

Before you provision​

Complete these items in order:

  1. Create the cloud account resources: registry, configuration bucket, parameter store namespace and secrets store.
  2. Seed the parameters and secrets for every role. Include the TelPro, Database and API port parameters that the firewall reads.
  3. Publish the configuration bundles for your release to the bucket and note the bundle reference for CONFIG_REF.
  4. Choose the image tag for ECR_TAG from Release compatibility.
  5. Create the DNS records from the previous section.
  6. Prepare a cloud access key for the hosts and the bastion SSH key pair.

Verify the prerequisites​

  1. From a workstation, resolve each DNS name and confirm that it points to the planned address.
  2. List the parameters under /<namespace>/<role>/ for each role, for example with aws ssm get-parameters-by-path --recursive, and confirm that the firewall port parameters exist.
  3. Confirm that the registry contains the images for your chosen tag.