Troubleshooting

Solutions for common installation problems.

Installation Issues

Docker Installation Fails

Symptom: Automatic Docker installation fails or times out.

Solution: Install Docker manually:

# Ubuntu/Debian
curl -fsSL https://get.docker.com | sudo bash
 
# CentOS/RHEL
sudo yum install -y docker-ce docker-ce-cli containerd.io
sudo systemctl start docker
sudo systemctl enable docker

Then retry installation:

sudo ./astervis-installer install --resume

License Validation Fails

Symptom: "License validation failed" or timeout error.

Possible causes:

Cause	Solution
No internet	Check connectivity: `curl -I https://api.astervis.io`
Firewall blocking	Allow outbound HTTPS (port 443)
Invalid key	Verify key format: `asp-xxxx-xxxx-xxxx`
Expired trial	Get new license at astervis.io

Image Pull Fails

Symptom: "Error pulling image" or timeout during installation.

Solutions:

# Check Docker Hub connectivity
docker pull hello-world
 
# If behind proxy, configure Docker
sudo mkdir -p /etc/systemd/system/docker.service.d
sudo nano /etc/systemd/system/docker.service.d/proxy.conf

Add:

[Service]
Environment="HTTP_PROXY=http://proxy:port"
Environment="HTTPS_PROXY=http://proxy:port"

Then:

sudo systemctl daemon-reload
sudo systemctl restart docker
sudo ./astervis-installer install --resume

Service Issues

Container Won't Start

Symptom: One or more containers show "Exit" status.

Diagnosis:

# Check which container failed
sudo astervis-installer status
 
# View container logs
docker logs astervis-<service-name>

Common causes:

Another service is using the port.

# Check what's using port 443
sudo lsof -i :443
 
# Stop conflicting service
sudo systemctl stop apache2  # or nginx, etc.

Database Won't Start

Symptom: Database service fails to start.

Check logs:

sudo astervis-installer logs --service database

Common fixes:

# Fix data directory permissions
sudo astervis-installer fix-permissions
 
# Or reinitialize database (WARNING: deletes data)
sudo astervis-installer database --reset

Sync Issues

No Data in Dashboard

Symptom: Dashboard shows no calls, but PBX is receiving calls.

Check sync status:

sudo astervis-installer status

If sync is not active:

sudo astervis-installer sync --reset

View sync logs:

sudo astervis-installer logs --service sync

MySQL Binary Logging

Symptom: Sync fails with "Binary log is not enabled" error.

Check binary logging:

sudo astervis-installer test-mysql --check-binlog

Enable binary logging (if disabled):

# Edit MySQL config
sudo nano /etc/mysql/mysql.conf.d/mysqld.cnf

Add under [mysqld]:

server-id = 1
log_bin = /var/log/mysql/mysql-bin.log
binlog_format = ROW
binlog_row_image = FULL
expire_logs_days = 7

Restart MySQL:

sudo systemctl restart mysql
# or on FreePBX
sudo fwconsole restart

Sync Lag

Symptom: New calls appear with delay (more than 30 seconds).

Check:

sudo astervis-installer status --verbose

Solutions:

Check disk I/O: iostat -x 1
Ensure SSD storage is used
Restart sync service: sudo astervis-installer restart --service sync

Network Issues

Can't Access Dashboard

Symptom: Browser shows "Connection refused" or timeout.

Checklist:

# 1. Check nginx is running
docker ps | grep nginx
 
# 2. Check nginx logs
docker logs astervis-nginx
 
# 3. Test local access
curl -k https://localhost:443
 
# 4. Check firewall
sudo ufw status
# or
sudo firewall-cmd --list-all

Allow port 443:

# Ubuntu (ufw)
sudo ufw allow 443/tcp
 
# CentOS (firewalld)
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --reload

SSL Certificate Issues

Symptom: Browser shows certificate error beyond normal self-signed warning.

Regenerate certificate:

sudo astervis-installer ssl --regenerate

For Let's Encrypt:

# Ensure domain points to server
dig +short your-domain.com
 
# Ensure ports 80 and 443 are open
sudo astervis-installer ssl --letsencrypt --domain your-domain.com

Recovery

Resume Failed Installation

sudo ./astervis-installer install --resume

The installer saves state and continues from the last successful step.

Complete Reinstall

If you need to start fresh:

# Uninstall (preserves data by default)
sudo astervis-installer uninstall
 
# Uninstall and remove all data
sudo astervis-installer uninstall --purge
 
# Reinstall
sudo ./astervis-installer install

Backup Before Reinstall

# Backup database
docker exec astervis-timescaledb pg_dump -U astervis astervis > backup.sql
 
# Backup configuration
cp /opt/astervis/.env ~/astervis-env-backup

Getting Help

If these solutions don't resolve your issue:

Check logs:
sudo astervis-installer logs > astervis-logs.txt
System info:
sudo astervis-installer status --verbose
Contact support: support@astervis.io with logs attached

Back to: Installation

Troubleshooting

On this page