Deploy on your infrastructure

Deployment models#

Core components#

The API contains the integration gateway. Workers contain the escalation and notification engines. PostgreSQL is authoritative; NATS JetStream transports committed outbox events. Redis is included in the on-prem Compose profile but is not required for incident correctness. The Web UI talks to a server-side API proxy.

Prepare the environment#

1. Obtain the approved source/release artifacts through your distribution channel. No public repository or license terms are asserted by this guide. Release images (backend, Web and the voice-gateway Asterisk image) are multi-architecture (linux/amd64 and linux/arm64), signed, with SBOM attestations; every binary reports its release with --version.
2. Provision private DNS, trusted certificates, stable time synchronization, storage, and backup destinations.
3. Build or mirror approved backend, Web, PostgreSQL, NATS, Redis, ingress and selected observability images. Use immutable digests where appropriate.
4. Prepare secrets locally, including the database and broker credentials, encryption key, and first-run setup token.
5. Run migrations before serving application traffic, then verify the first organization workflow. Both deployment profiles run the paging upgrade check before migrating.

Small-install Compose#

cp deploy/onprem/.env.example /secure/path/acknexa.env
bash scripts/onprem_init.sh /secure/path/acknexa-config

# Configure approved images, paths, private DNS and TLS files first.
docker compose --env-file /secure/path/acknexa.env \
  -f deploy/onprem/compose.yml --profile observability up -d --wait

Run these commands from the product repository. Initialization refuses to overwrite an existing configuration directory. Supply ca.crt, tls.crt, and tls.key from customer PKI, update ingress hostnames, and set the exact HTTPS Web origin. The profile preloads images with pull_policy: never and does not seed demo data.

Production Helm#

helm upgrade --install acknexa ./deploy/helm/acknexa \
  --namespace acknexa \
  -f deploy/helm/acknexa/values-onprem.yaml \
  -f /secure/path/site-values.yaml \
  --atomic --wait --timeout 15m

Pre-create the namespace, private-registry credentials, customer CA ConfigMap, state-service Secrets, application encryption key, and ingress TLS Secrets. Supply actual image digests and ingress/resource/topology values. PostgreSQL uses verified TLS and separate runtime/migration identities. NATS uses authenticated TLS seeds and a replicated file-backed stream.

The chart deploys stateless application components, not the customer's entire HA platform. Database operators, NATS clusters, ingress controllers and independent monitoring are customer-managed. A private VIP, hardware appliance or internal load balancer can replace a cloud load balancer.

Private-network and disconnected operation#

Mirror images and build dependencies before disconnecting. Runtime isolation does not automatically provide an offline build cache. Private-registry CA trust must be installed on container nodes; the application's CA mount cannot fix image pulls. Build the Web image with the private API URL so its integration instructions display the correct address.

The on-prem Compose backend network is internal by default. Reach customer LAN services through an approved network attachment or a customer-only firewall allowlist. The Helm overlay supplies restricted egress; use an enforcing CNI and add explicit rules for dependencies outside the namespace. Do not assume NetworkPolicy alone covers every host or ingress path.

Configuration overlays#

• Internal OIDC: deploy/onprem/oidc.compose.yml.
• SMTP authentication: deploy/onprem/smtp-auth.compose.yml.
• Customer voice gateway for paging calls: deploy/onprem/voice.compose.yml.
• CUCM gateway for live call routing: deploy/onprem/voice-gateway.compose.yml, or the Helm voiceGateway values. Include the overlay in every later Compose command, upgrades too.
• Android push through FCM: deploy/onprem/fcm.compose.yml.
• Helm adapters are opt-in via oidc.enabled and notifications.*.enabled (including notifications.fcm and notifications.pushRelay; the push relay cannot be combined with APNs or FCM). Disabled adapters do not require their cloud credentials.
• Set PROVIDER_CALLBACK_BASE_URL (Helm config.providerCallbackBaseURL) when Twilio, call routing or ticketing inbound webhooks are used.