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.

Role	Main services	Public address	Internet access
Web	TelWeb behind Caddy	Yes	Direct
API	TelAPI behind an HTTPS load balancer	No	Through the Squid proxy
Voice	TelSys, TelPhi, AudioProc	No	Through the Squid proxy
Ops	Scaler, Tasker, one-shot database migration	No	Through the Squid proxy
Media	Media server behind Caddy	No	Through the Squid proxy
TelPro	Kamailio, RTPEngine, Janus, coturn	Yes	Direct
Database	PostgreSQL, PgBouncer, Redis	No	Through the Squid proxy
SigNoz	Telemetry storage, dashboards and alerts	No	Through the Squid proxy
Squid	Outbound HTTP proxy for private hosts	Yes	Direct
Bastion	SSH entry point to every other host	Yes	Direct

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.

Role	Port or range	Protocol	Purpose	Source
Web	80, 443	TCP	TelWeb and the optional SigNoz UI over HTTPS	Users
API load balancer	443	TCP	Public TelAPI; forwards to TELAPI_PORT (default 3001)	API clients
TelPro	SIP_PORT (default 5060)	UDP, TCP	SIP from carriers and trunks	Carriers
TelPro	SIPS_PORT (default 5061)	TCP	SIP over TLS	Carriers
TelPro	JANUS_WS_PORT (default 443)	TCP	Janus browser WebSocket	Browsers
TelPro	TURN_PORT, TURN_TLS_PORT (3478, 5349)	UDP, TCP	TURN for browser voice	Browsers
TelPro	RTP_PORT_MIN–RTP_PORT_MAX (20000–40000)	UDP	RTPEngine media for carrier calls	Carriers
TelPro	JANUS_RTP_PORT_MIN–JANUS_RTP_PORT_MAX (10000–12000)	UDP	Janus media for browser calls	Browsers
TelPro	TURN_MIN_PORT–TURN_MAX_PORT (49152–51152)	UDP	TURN relay	Browsers
Database	POSTGRES_PORT, REDIS_PORT	TCP	Database and Redis	Private network
Media	443	TCP	Media uploads and playback	Private network
SigNoz	4317, 4318	TCP	Telemetry from the collectors	Private network
Squid	3128	TCP	Outbound proxy	Private network
All	22	TCP	SSH from the bastion	Bastion or private network

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.

Need	Used for
Container registry	Every role pulls its images from ECR_REGISTRY with the tag in ECR_TAG.
Configuration bucket	Each host downloads its role bundle from CONFIG_BUCKET.
Parameter store	Non-secret values under your deployment namespace, shared or per role.
Secrets store	Secret values under your deployment namespace, per role.
Cloud access key per host	Lets the host log in to the registry and read the bucket, parameters and secrets.
Server cloud project token	Creates hosts, networks, firewalls and the load balancer; Ops uses it for scaling and DNS-based certificate renewal.
SSH key pair for the bastion	The 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.

Related

• Provision instances and bootstrap a role: to create the hosts once the prerequisites are in place.
• Environment variable reference: to find every variable a role expects.
• Release compatibility: to choose the image tag and supported upstream versions.
• Service topology: to see how the roles depend on each other.