Debian package

For bare metal, any VPS provider (Hetzner, Vultr, DigitalOcean, Linode, OVH, on-prem, etc.), or an existing Debian 12 host, jambonz publishes a .deb package that installs the whole single-host stack from apt. This is the simplest deployment path when you’re not on AWS / Azure / GCP / OCI and don’t want to use one of the prebuilt images.

Prerequisites

• Debian 12 (bookworm), amd64
• sudo access
• At least 4 vCPU, 8 GB RAM, 100 GB disk
• Public IPv4 address
• Network rules / firewall configured to allow the ports below

Required open ports

How you open these depends on your provider — security groups on a cloud VPS, an OS-level firewall (ufw, nftables) on bare metal, or a hardware firewall in front. Consult your provider’s documentation.

Add the apt sources

Four apt sources are required: the jambonz repository itself, plus three upstream sources that ship dependencies Debian doesn’t include directly.

$
sudo apt-get update -qq
$
sudo apt-get install -y -qq curl ca-certificates gnupg systemd
$
$
# 1. jambonz APT source
$
sudo install -d /etc/apt/keyrings
$
curl -fsSL https://jambonz-debian-packages.s3.us-east-2.amazonaws.com/jambonz.gpg \
>
  | sudo gpg --dearmor -o /etc/apt/keyrings/jambonz.gpg
$
echo "deb [signed-by=/etc/apt/keyrings/jambonz.gpg] https://jambonz-debian-packages.s3.us-east-2.amazonaws.com/debian bookworm main" \
>
  | sudo tee /etc/apt/sources.list.d/jambonz.list
$
$
# 2. InfluxData APT source (for telegraf — not in Debian's repos)
>
curl -fsSL https://repos.influxdata.com/influxdata-archive.key \
>
  | sudo gpg --dearmor -o /etc/apt/keyrings/influxdata.gpg
>
echo "deb [signed-by=/etc/apt/keyrings/influxdata.gpg] https://repos.influxdata.com/debian stable main" \
>
  | sudo tee /etc/apt/sources.list.d/influxdata.list
>
>
# 3. NodeSource APT source (Node 22 — Debian ships 18)
>
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
>
>
# 4. Grafana APT source (for the metrics dashboard)
>
curl -fsSL https://apt.grafana.com/gpg.key \
>
  | sudo gpg --dearmor -o /etc/apt/keyrings/grafana.gpg
>
echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" \
>
  | sudo tee /etc/apt/sources.list.d/grafana.list
>
>
sudo apt-get update

Choose your portal DNS name

Pick a hostname you control DNS for. The installer will configure nginx for that name and these related subdomains:

• portal.example.com — the admin webapp
• api.portal.example.com — the REST API
• grafana.portal.example.com — metrics dashboards

You should create A records for all of the above pointing at your host’s public IP. You can do this before or after the install, but it must be done before you obtain TLS certificates with certbot. See Post-Install Steps for the DNS record list.

Supplying the domain to the installer

You have three options:

1. Inline on the install command (recommended / simplest):

   $
   sudo -E JAMBONES_PORTAL_DOMAIN=portal.example.com \
   >
     DEBIAN_FRONTEND=noninteractive apt-get install -y jambonz-mini

   The -E flag preserves the environment variable through sudo.

2. Pre-supply via /etc/jambonz/install.conf (good for terraform / ansible / cloud-init):

   $
   sudo install -d /etc/jambonz
   $
   echo "JAMBONES_PORTAL_DOMAIN=portal.example.com" | sudo tee /etc/jambonz/install.conf

   Then run the normal install — the postinst will read install.conf automatically.

3. Configure it after installing, if you forgot:

   $
   sudo jambonz-configure-domain portal.example.com

   This idempotent helper:

   • Writes the nginx config (vhosts for portal.example.com, api.portal.example.com, grafana.portal.example.com) and reloads nginx
   • Writes JAMBONES_PORTAL_DOMAIN to /var/lib/jambonz/host.env
   • Updates the system_information row in MySQL (required for drachtio’s license validation)
   • Restarts drachtio, freeswitch, and the jambonz Node services so they pick up the new domain

   Safe to re-run any number of times. Same logic the postinst runs with the env var set.

If you install without specifying a domain, the install completes but the postinst prints a NO PORTAL DOMAIN configured warning — license validation will not succeed until you run jambonz-configure-domain.

Install jambonz mini

rtpengine includes a kernel module that DKMS will compile on the host, so the matching Linux headers must be installed first. Then run the install with your portal domain:

$
sudo apt-get install -y linux-headers-cloud-amd64 || sudo apt-get install -y linux-headers-$(uname -r)
$
sudo -E JAMBONES_PORTAL_DOMAIN=portal.example.com \
>
  DEBIAN_FRONTEND=noninteractive apt-get install -y jambonz-mini

apt resolves the full dependency tree (jambonz-common, jambonz-monitoring-agent, jambonz-rtpengine, jambonz-rtpengine-dkms, drachtio, jambonz-freeswitch, telegraf, nodejs, MariaDB, Redis, nginx, Grafana).

What the postinst did

While apt was running, the jambonz-common and jambonz-mini post-install scripts:

• Created the jambonz system user with passwordless sudo and copied the cloud-init user’s SSH authorized_keys so you can ssh jambonz@<host> with the same keypair
• Generated per-host secrets in /var/lib/jambonz/secrets.env (mode 600 — JWT signing key, MySQL password, Homer/heplify credentials, recording auth)
• Auto-detected the host’s local subnet and wrote it to /var/lib/jambonz/host.env
• Waited for MariaDB, then created the jambones database, ran the schema and seed, and applied any pending migrations
• Wrote systemd drop-ins for drachtio and FreeSWITCH so they pick up the generated DB/Redis credentials
• Set up PostgreSQL plus the HEP / SIP-capture stack (heplify-server + pcap-server) with a generated heplify role and the homer_data / homer_config databases
• Configured InfluxDB and Grafana (moved Grafana to port 3010 to avoid colliding with the Node apps on 3000)
• Configured the upload_recordings C++ daemon with the matching ENCRYPTION_SECRET so it can decrypt bucket credentials
• Checked the rtpengine DKMS kernel module against the running kernel — building it if headers are available, or queueing a REBOOT RECOMMENDED warning if a newer kernel was installed
• Wrote the nginx config (vhosts for portal / api / grafana if a portal domain was supplied, otherwise a catch-all on the default server) and reloaded nginx
• Enabled and started the jambonz-apps.target systemd target and its child services, plus drachtio, FreeSWITCH, rtpengine, heplify-server, pcap-server, InfluxDB, and Grafana

On a clean install this completes in a minute or two.

Verify the install

$
echo "=== mysql admin user ==="
$
sudo mysql -e "SELECT user, host FROM mysql.user WHERE user='admin';"
$
$
echo "=== schema version ==="
$
sudo mysql -e "USE jambones; SELECT version FROM schema_version;"
$
$
echo "=== telegraf listening on :8125 ==="
$
sudo ss -tnlp '( sport = :8125 )'
$
$
echo "=== systemd units ==="
$
systemctl --no-pager list-units 'jambonz-*' --all
$
$
echo "=== webapp returns HTTP 200 ==="
$
curl -sI http://localhost/ | head -1
$
$
echo "=== no ECONNREFUSED in recent logs (should be 0) ==="
$
sudo journalctl -u 'jambonz-*' -n 200 --no-pager 2>/dev/null | grep -c 'ECONNREFUSED.*8125'

All jambonz-* units should be active (running). The webapp should return HTTP/1.1 200 OK. The ECONNREFUSED count should be 0.

Post-install steps

Before logging in for the first time, complete these steps:

• DNS records and HTTPS — see the Post-Install Steps article. It walks through creating the A records (api. and grafana.) and using certbot to obtain a TLS certificate for the portal.
• WebRTC and SIP TLS — see Setting up WebRTC and SIP TLS if you need WSS or SIPS.
• Licensing — obtain a license key as described in the Licensing article. Free trial licenses are available; extended licenses for non-commercial use and pre-revenue startups can be requested at support@jambonz.org.

First login

Browse to your portal’s DNS name (e.g. https://my-domain.example.com) and log in with:

• Username: admin
• Password: admin

You’ll be required to set a new password on first login.

Logging in as the jambonz user

The install creates a jambonz system user with passwordless sudo and copies the cloud-init user’s SSH keys into /home/jambonz/.ssh/authorized_keys. Day-2 operations are intended to be performed as this user — not as root, admin, ubuntu, or ec2-user.

$
ssh jambonz@<this-host>

You should see this user mentioned in the final lines of the install output. Once logged in, the jambonz CLI is on $PATH and sudo works without a password prompt.

The jambonz CLI

The jambonz-common package ships a jambonz command at /usr/bin/jambonz for day-2 operations. Run it as the jambonz user:

Tailing logs

Common usage:

$
# Stream every jambonz Node app's journal, live
>
jambonz logs -f
>
>
# Same, scoped to one app (short form — "feature-server" → jambonz-feature-server)
>
jambonz logs -f feature-server
>
>
# Print recent logs and exit (no -f)
>
jambonz logs api-server
>
>
# For non-Node services, pass the full unit name
>
jambonz logs -f drachtio
>
jambonz logs -f freeswitch

App-name resolution is forgiving: short forms like feature-server, api-server, inbound, outbound are expanded to their jambonz-* unit names. For drachtio, FreeSWITCH, and rtpengine — which aren’t part of the jambonz Node-app set — pass the full unit name.

Customizing config

Environment variables for the Node apps come from four files, layered in order — later files override earlier ones on conflict:

1. /etc/jambonz/jambonz.env — shared, customer-editable config
2. /etc/jambonz/<app>.env — per-app overrides (e.g. feature-server.env)
3. /var/lib/jambonz/host.env — per-host runtime (auto-generated; also the right place for terraform/ansible to write)
4. /var/lib/jambonz/secrets.env — generated cluster secrets, mode 600

Files you can edit (conffile-protected)

These files are tracked by dpkg. Your edits survive upgrades; if a release ships a new default you’ll be prompted (see Upgrading below).

Files that are generated — do NOT edit

These get rewritten on every upgrade. Edits will be lost. If you need to change a value, edit the source env file instead.

After editing any of the conffile-protected files above, apply with:

$
sudo systemctl restart jambonz-apps.target

Adding custom systemd directives

If you need extra Environment= or ExecStartPre= directives on a system unit (for example to enable SIP over TLS on drachtio), don’t edit the shipped service file or the jambonz*.conf drop-ins — both get reset on upgrade. Create your own drop-in whose name does not start with jambonz:

$
sudo install -d -m 755 /etc/systemd/system/drachtio.service.d
$
sudo tee /etc/systemd/system/drachtio.service.d/local.conf >/dev/null <<'EOF'
$
[Service]
$
ExecStartPre=/usr/local/sbin/setup-tls-cert.sh
$
Environment="DRACHTIO_EXTRA_ARGS=--sips-port 5061"
$
EOF
$
$
sudo systemctl daemon-reload
$
sudo systemctl restart drachtio

jambonz upgrades will never touch a drop-in not named jambonz*.conf. Your local.conf survives every upgrade.

Upgrading

The simplest path:

$
sudo jambonz upgrade

This refreshes apt indexes, lists which jambonz packages have new versions, asks for confirmation, runs the upgrade, and finishes with a jambonz health so you immediately see whether anything came back failing. If there’s nothing new, it’s a no-op with a clean message.

The equivalent raw apt commands:

$
sudo apt-get update
$
sudo apt-get upgrade

Schema migrations run automatically — the jambonz-mini postinst detects the existing schema_version table, skips the seed, and applies only pending migrations. Existing data is preserved.

Conffile prompts

If an upgrade ships a new default for a config file under /etc/ and you’ve edited that file, dpkg will prompt you:

Configuration file '/etc/jambonz/feature-server.env'
 ==> Modified (by you or by a script) since installation.
 ==> Package distributor has shipped an updated version.
   What would you like to do about it?  Your options are:
    Y or I  : install the package maintainer's version
    N or O  : keep your currently-installed version
      D     : show the differences between the versions
      Z     : start a shell to examine the situation
 The default action is to keep your current version.
*** feature-server.env (Y/I/N/O/D/Z) [default=N] ?

The default (N — keep your edits) is almost always the right answer for env files. Press D first to see what changed — sometimes the new version adds variables worth adopting, in which case keep your file with N and add the new variables manually.

Recommended pre-upgrade ritual

For production boxes:

$
# 1. Snapshot the database
$
sudo mysqldump --single-transaction --routines --triggers jambones \
>
  > /tmp/jambones-$(date +%F).sql
$
$
# 2. Capture current versions for rollback reference
$
jambonz version > /tmp/versions-before.txt
$
$
# 3. Confirm the system is healthy before upgrading
$
jambonz health
$
$
# 4. Upgrade
$
sudo jambonz upgrade
$
$
# 5. Confirm health after (jambonz upgrade does this automatically too)
$
jambonz health

Rolling back

If an upgrade breaks something and you need to drop back to a previous version:

$
# Show available versions
$
apt-cache madison jambonz-mini
$
$
# Pin back to a specific version
$
sudo apt-get install --allow-downgrades \
>
  jambonz-mini=10.1.5 \
>
  jambonz-common=10.1.5

Schema migrations do not auto-roll-back — once new tables or columns exist, they persist. That’s safe because the migration policy guarantees backward compatibility (no DROP TABLE, no new NOT NULL columns without defaults), so old code reading a newer schema works correctly. You don’t need to restore the database to roll back code.

If you ever do need the schema rolled back, restore MySQL from your pre-upgrade backup before downgrading the deb.

Removing

$
sudo apt-get purge jambonz-mini jambonz-common jambonz-monitoring-agent

apt-get purge removes configuration files but does not drop the jambones database — your data is preserved. For a true reset, drop it manually:

$
sudo mysql -e "DROP DATABASE jambones; DROP USER 'admin'@'%';"

Troubleshooting

$
sudo grep JAMBONES_MYSQL_PASSWORD /var/lib/jambonz/secrets.env
$
sudo mysql -uroot -e "SELECT user FROM mysql.user WHERE user='admin'\\G"

$
jambonz env feature-server | grep -i record

$
sudo cat /etc/systemd/system/drachtio.service.d/jambonz-execstart.conf

Known limitations