Installation & Server Guide

1. Choose one installation method

Method A: install Debian 12 amd64 using your provider, then use the online installer below. Method B: boot the RingTelix ISO using your provider’s virtual CD/DVD and complete Debian installation, then run ringtelix-setup. Choose one method; mounting a file alone does not install an operating system.

2. Debian and root access

Use a fresh Debian 12 (bookworm), x86_64 server with its own public IPv4 address. Open your provider console or SSH terminal. These are Linux server commands, not Windows CMD commands. If logged in as an ordinary user, become root first:

su -

Enter the Linux root password privately. If your provider uses sudo instead, use sudo -i. Do not run the fresh installer over a working switch.

3. Check the target before changing it

Confirm the IP belongs to the server you intend to install. Debian VERSION_ID should be 12 and uname should show x86_64.

hostname
ip -br -4 addr show scope global
cat /etc/os-release
uname -m
df -h /
for p in /opt/ringtelix /var/lib/ringtelix-install/core.json; do
  if [ -e "$p" ]; then echo "EXISTING INSTALLATION: $p"; fi
done

If an existing installation is reported, use Resume or Updates. Do not remove its state, database or license identity to force a fresh installation. Space checks in the installer are minimum checks, not a capacity specification.

4. Update a fresh Debian server

Run before RingTelix installation. Review the proposed Debian upgrades before accepting; this can install a new kernel. Keep the provider console available.

apt-get update &&
apt-get upgrade &&
apt-get install -y ca-certificates curl python3 openssl util-linux &&
timedatectl status

If the provider or package manager requires a reboot, run reboot, wait, reconnect, and continue with DNS and installer setup. Do not run Debian upgrades or reboot during active customer calls.

5. Prepare domain and DNS

Choose a dedicated hostname such as switch.example.com. Create an A record pointing to this server’s real public IPv4. Remove or correct a conflicting AAAA record if the installer reports it. For a proxied DNS service, use DNS-only during setup. Ensure inbound TCP 80/443 reaches this server for certificate validation. Do not change the SSH port or firewall blindly.

getent ahostsv4 switch.example.com

Replace switch.example.com with your real hostname. The returned address must match the server. DNS propagation can take time. The installer verifies DNS and HTTPS before proceeding. SIP/media networking needs its own checks; HTTPS success does not prove voice readiness.

6A. Run the online installer — fresh Debian only

Run as root in the interactive SSH terminal. The first command downloads the public bootstrap; bash runs only if curl succeeds. Keep this terminal connected and answer the prompts.

curl --fail --show-error --location \
  --proto '=https' --proto-redir '=https' \
  https://www.ringtelix.com/install.sh \
  -o /root/ringtelix-install.sh &&
bash /root/ringtelix-install.sh

The bootstrap checks the signed installer channel, archive size, SHA256 and member inventory. It refuses an existing switch. Do not pipe it into a noninteractive shell or bypass signature errors. If download fails before setup starts, retry this block. Once setup has started, use Resume below.

7. Answer setup prompts

Enter your hostname, the server public IP and certificate email when requested. Correct DNS and resume if verification pauses. Enter the requested company/registration details. Choose your administrator username and type the password twice (the current prompt requires at least 14 characters). Password characters may be invisible while typing. Linux root and switch administrator passwords are separate.

If passwords do not match, enter both again. If account setup reports HTTP 400, do not assume installation completed: inspect API health/logs and resume. Never post passwords, database environment files, recovery codes or private keys in support screenshots.

6B. Install using the RingTelix ISO

Download the published RingTelix ISO from Downloads. In the server provider panel, attach it as virtual CD/DVD and boot the server from it. Complete Debian installation on the intended disk, then detach/eject the ISO and boot the installed disk. Disk partitioning can erase data: use the fresh target server only. Log in as root; the ISO first-login hook may start setup automatically.

ringtelix-setup

Run this if the ISO setup did not start or was paused. It is for a machine actually installed from the RingTelix ISO. It is not guaranteed to exist on plain Debian. The ISO setup normally checks the published release; it needs internet access. Do not set RINGTELIX_USE_EMBEDDED=1 as a normal customer installation step. Merely mounting the ISO on an already running Debian server does not create ringtelix-setup; use method A instead.

8. SSH disconnected or installation paused

Reconnect to the same server as root. First check whether setup is still running. Do not launch a second copy.

ps -eo pid,etime,stat,args | grep -E '[i]nstall_core.py|[p]ackage/install.py|[r]ingtelix-setup|[r]ingtelix-channel'

If a process is still running, wait or ask support to inspect it. A closed SSH window does not prove the installer stopped. Never delete locks or kill package-manager processes to bypass a busy message.

9. Resume the original package

After confirming no installer is running: for an ISO installation use ringtelix-setup. For an online installation use this block. It chooses the original package by the saved checkpoint; if it cannot choose exactly one it stops rather than guessing.

python3 -B - <<'PYRESUME'
from pathlib import Path
import hashlib, json, os
state=Path('/var/lib/ringtelix-install/core.json')
paths=[]
for base in ('/var/lib/ringtelix-downloads','/var/lib/ringtelix-installer'):
    root=Path(base)
    if root.is_dir():
        for p in root.glob('*/package/install.py'):
            if p.is_file() and not p.is_symlink(): paths.append(p)
        for p in root.glob('*/install.py'):
            if p.is_file() and not p.is_symlink(): paths.append(p)
paths=list(dict.fromkeys(paths))
if state.exists():
    expected=json.loads(state.read_text()).get('package_sha256')
    if not expected: raise SystemExit('STOP: package checkpoint missing; contact support')
    paths=[p for p in paths if (p.parent/'SHA256.json').is_file()
           and hashlib.sha256((p.parent/'SHA256.json').read_bytes()).hexdigest()==expected]
if len(paths)!=1:
    print('STOP: Cannot choose one original installer. Contact support. Candidates:')
    for p in paths: print(p)
    raise SystemExit(1)
print('Resuming original installer:',paths[0],flush=True)
os.execv('/usr/bin/python3',['python3','-B',str(paths[0])])
PYRESUME

Do not delete /var/lib/ringtelix-install/core.json or alter SHA256.json to restart. A database_allocating checkpoint requires support inspection; the installer intentionally refuses an automatic database wipe. This selector locates the saved package; it does not replace the installer’s own validation.

10. Correct a mistyped domain before installation progresses

On the ISO path only, this helper can reset a pending domain while the setup is still planned/dns_pending. It refuses once switch installation or certificate setup has progressed.

ringtelix-setup --reset-domain

Read the displayed hostname and type RESET only if correct. On the direct online path, or after installation has progressed, contact support for the appropriate correction/migration. Do not delete domain.json or manually rename an installed switch domain.

11. Finish, reboot and first login

Wait for the final installer output. Record the displayed HTTPS dashboard address and administrator username privately. If the installed build offers Reboot now? [y/N], choose y only when ready for SSH to disconnect. Some published builds may only print a reboot instruction; the newer prompt is not guaranteed in every installer.

reboot

Run this once only after setup finishes and when prompted/instructed. Reconnect after the server boots, then open the displayed dashboard. Do not repeatedly rerun a completed installer or repeatedly reboot to fix a license error.

12. Check the installed system

Run after reconnecting. Healthy API means the web service is responding; it does not certify SIP calls, media, charging or a license.

systemctl is-active ringtelix-api.service
curl -fsS --max-time 10 http://127.0.0.1:8100/health
echo
ringtelix-update status
journalctl -u ringtelix-registration.service -b -n 40 --no-pager -o cat

Open Settings → License and verify signed entitlement, expiry, channels and CPS. Expired/revoked entitlements do not become a fresh trial after reinstall. Remaining valid entitlement must be recovered/replaced through the supported licensing flow. A duplicate record or pending registration may require owner action; reboot does not grant days.

13. Update RingTelix after installation

Use the switch Software Updates screen to check available updates and apply the offered version. Back up first and schedule changes outside active calls. Do not use the fresh install.sh bootstrap as an upgrade command.

ringtelix-update status
ringtelix-update --help

The status command is verified in this installation. Use the exact apply/check syntax reported by your installed tool or the dashboard; this guide does not invent an upgrade subcommand. Debian package updates and RingTelix application updates are separate operations.

14. Change or recover the Linux password

When already logged in as root, use passwd and enter the new password twice. It changes the Linux root password, not the switch web administrator password.

passwd

To change an ordinary Linux user password as root: passwd USERNAME (replace USERNAME). If root access is lost, use your hosting provider’s console/rescue/password-reset procedure. The web dashboard cannot reset the Linux root password.

15. Change or recover the switch administrator password

While signed in: Settings → My Account → Change Password. Enter current/new/repeated password and save. If you cannot sign in, contact RingTelix support using the registered account and server IP. The owner can use the central password recovery tool for that exact installation.

The central v719 password recovery feature exists, but this source export does not establish every installed client’s recovery command or delivery path. Follow the owner-issued recovery instructions for your server. Never edit password hashes, bootstrap-owner.json or the database as a generic reset method. Changing Linux passwd does not change the web login.

16. Common stops and what to do

DNS/SSL pending: correct the displayed record/network access, then resume the original installer. Signature or clock error: verify server time/network; do not bypass signature verification. Existing installation: use Resume or Updates. Setup already running: inspect/wait. HTTP 400 during owner creation: inspect the API and contact support with sanitized errors.

date -u
timedatectl status
systemctl status ringtelix-api.service --no-pager -l
journalctl -u ringtelix-api.service -b -n 60 --no-pager -o cat

Before sharing logs, remove passwords, tokens, personal details and private addresses as appropriate. If a command fails, keep the error and checkpoint; do not delete the database, license files or installer state. No repeated reboot, fresh trial or new customer entitlement is implied by these checks.