Installation Troubleshooting

Most installs finish clean. The ones that don't almost always fail for one of a handful of reasons — a hardened-host kernel setting, a firewall that quietly blocks the Docker bridge, or stale data left over from an earlier attempt. The good news: the installer already self-heals most of these and retries on its own. This page covers the failures you might still see, framed as symptom → cause → fix, so you can recognise what's happening and confirm the remedy.

Before you dig in: read the log

Every install writes a single log file, and its path is printed near the top of the run as Logs: .... On a startup failure the installer also dumps per-container Compose diagnostics — service states, logs, sysctl net.ipv4.ip_forward, and ip route — into that same file. So in almost every case there is exactly one file that tells the whole story.

Connection timeout despite a healthy database

This is the most common hardened-host failure, and the symptom is misleading: TimescaleDB reports healthy, but migrate or app die with Connection terminated due to connection timeout. The database is fine — the kernel is dropping the packets between containers.

There are two distinct causes. The installer detects and remediates both, but it's worth understanding which one you hit.

sysctl -w net.ipv4.ip_forward=1
echo 'net.ipv4.ip_forward = 1' >> /etc/sysctl.conf

Empty call history, or operator import times out

Symptom. The install completes, but the dashboard shows no calls, or the "import operators from Asterisk" step times out with ETIMEDOUT / Communications link failure ... 0 milliseconds ago.

Cause. Your host's INPUT firewall has a policy drop that blocks the Docker bridge subnet (172.16.0.0/12) from reaching MySQL on port 3306 — even though MySQL itself binds 0.0.0.0. The replication consumer and the operator importer can't reach the CDR database, so nothing flows in.

The fix differs depending on whether your host uses iptables or native nftables — an iptables rule lands in a table the nft hook ignores, so you have to target the right firewall.

iptables -I INPUT -p tcp --dport 3306 -s 172.16.0.0/12 -j ACCEPT

Re-install: "password authentication failed"

Symptom. You re-run the install on a server that had Astervis before, and migrate fails with:

password authentication failed for user "astervis"

Cause. TimescaleDB persists its data directory (timescaledb_data) between attempts. POSTGRES_PASSWORD only takes effect on the first PGDATA initialisation — but every fresh install regenerates a new random password into .env. So the role still has the old password while .env carries a new one, and they no longer match.

Fix. The installer detects this (MigrateAuthFailed) and reconciles the role password to match .env over the local trust socket, then retries automatically (since v0.0.79). You normally don't need to do anything but let it run.

If you want a guaranteed-clean slate instead, do a real teardown first — the uninstall command became a genuine teardown in v0.0.83 (earlier versions were a no-op that printed success while leaving everything running):

sudo astervis-installer uninstall          # removes containers, images, units, /opt/astervis
sudo astervis-installer install --license AST-XXXX-XXXX-XXXX-XXXX...

litcdc container OOM-loops on the first snapshot

Symptom. The astervis-litcdc container restarts over and over with exit code 137 during the very first run, and call history never backfills.

Cause. litcdc is the Rust CDC service that replaced the old Debezium + Redpanda pipeline. On first run it takes a consistent snapshot of the cdr table, and redb memory-maps the table to do it. On busy PBXes (~64k+ CDR rows) that mapping didn't fit inside the old 128 MB container limit, so the kernel OOM-killed it on a loop.

Fix. The current settings are mem_limit: 256m, a 64 MiB buffer cap (LITCDC_BUFFER_MAX_BYTES=67108864), and REPLICATION_THROTTLE_MS=0 so the consumer drains at full speed and keeps the buffer shallow. Fresh installs from v0.0.84 (with litcdc ≥ 0.1.3) ship these by default — nothing to do.

If you hit this on a server that's already running, note that upgrade self-updates the installer binary only; it does not regenerate docker-compose.yml. You have to edit the litcdc service in /opt/astervis/docker-compose.yml and recreate it:

litcdc:
  mem_limit: 256m
  environment:
    LITCDC_BUFFER_MAX_BYTES: "67108864"

cd /opt/astervis
docker compose up -d --force-recreate litcdc replication

The durable buffer lives on a host-mounted volume (litcdc_data), so once the snapshot completes it never re-snapshots on restart.

Image pull, Docker, and database basics

Most of the classic "it won't start" failures are handled for you. Here's what the installer does automatically, and the few cases where you may need to step in.

Run the system check yourself

Most install-time surprises are caught up front by Step 1/4 — the system check. It validates platform, RAM (2 GB minimum), CPU (1 core minimum), free disk (15 GB, measured on the Docker data-root partition, not /), a detected PBX, the MySQL CDR credentials, internet, and Docker. A failed hard requirement aborts the install with a clear message. To see the current state of a running deployment:

sudo astervis-installer status

Still stuck?

If the single install log doesn't get you there, send it to support@astervis.io and we'll take it from there.