Troubleshooting

Common issues and solutions for PanelAlpha Snapshot Tool.

Quick Diagnostics

# Check logs for errors
sudo tail -50 /var/log/pasnap.log

# Test storage connection
sudo ./pasnap.sh --test-connection

# Verify Docker is running
sudo systemctl status docker

# Check disk space
df -h

Common Issues

Permission Denied

Symptom: Permission denied errors when running commands.

Solution: Always run with sudo:

sudo ./pasnap.sh --snapshot

Docker Not Running

Symptom: Cannot connect to Docker daemon or similar errors.

Solution:

# Start Docker
sudo systemctl start docker

# Enable Docker to start on boot
sudo systemctl enable docker

# Verify Docker is running
sudo systemctl status docker

Repository Connection Failed

Symptom: unable to open config file or connection timeout errors.

Solution:

Test the connection:
```
sudo ./pasnap.sh --test-connection
```

Verify configuration:

sudo cat /opt/panelalpha/app/.env-backup

For S3:
Check AWS credentials are correct
Verify bucket exists and is accessible
Check region is correct
For SFTP:
Verify SSH key is set up
Test SSH connection manually: ssh user@hostname
Check remote directory exists

Insufficient Disk Space

Symptom: no space left on device errors.

Solution:

Check available space:
```
df -h /var/tmp
df -h /
```

Clean up old snapshots:

sudo ./pasnap.sh --list-snapshots
sudo ./pasnap.sh --delete-snapshots <old-snapshot-id>

Clean Docker resources:
```
docker system prune -f
```

Database Backup Fails

Symptom: Errors related to MySQL or database dumps.

Solution:

Check if PanelAlpha is running:

cd /opt/panelalpha/app  # or /opt/panelalpha/engine
docker compose ps

Verify database container is healthy:
```
docker compose logs database-api
```
Check database credentials in .env file

Try restarting containers:

docker compose down
docker compose up -d

Snapshot Restoration Fails

Symptom: Errors during --restore operation.

Solution:

Ensure PanelAlpha is stopped:

cd /opt/panelalpha/app
docker compose down

Check disk space is sufficient
Verify snapshot exists:
```
sudo ./pasnap.sh --list-snapshots
```
Check logs for specific errors:
```
sudo tail -100 /var/log/pasnap.log
```

Cron Job Not Running

Symptom: Automatic backups are not being created.

Solution:

Check cron status:
```
sudo ./pasnap.sh --cron status
```
View cron jobs:
```
sudo crontab -l
```
Check cron service:
```
sudo systemctl status cron
```

Reinstall cron job:

sudo ./pasnap.sh --cron remove
sudo ./pasnap.sh --cron install

SSL Certificate Issues After Restore

Symptom: SSL errors or certificate warnings after restoration.

Solution:

Regenerate certificates:

cd /opt/panelalpha/app
docker compose exec nginx certbot renew --force-renewal

Restart nginx:
```
docker compose restart nginx
```

Log Analysis

View Recent Logs

sudo tail -f /var/log/pasnap.log

Search for Errors

sudo grep -i error /var/log/pasnap.log

Search for Specific Date

sudo grep "2024-01-15" /var/log/pasnap.log

Getting Help

If you're still experiencing issues:

Collect diagnostic information:

# System info
uname -a
docker --version

# Recent logs
sudo tail -100 /var/log/pasnap.log > pasnap-debug.log

# Storage test
sudo ./pasnap.sh --test-connection 2>&1 >> pasnap-debug.log

Open an issue on GitHub:
GitHub Issues
Include the diagnostic information (remove sensitive data)

Recovery Procedures

Complete Reset

If the tool is in an inconsistent state:

# Remove configuration
sudo rm /opt/panelalpha/app/.env-backup

# Reinstall
sudo ./pasnap.sh --install

# Reconfigure
sudo ./pasnap.sh --setup

Manual Database Restore

If automatic restore fails, you can manually restore the database:

# Extract database dump from snapshot (contact support for assistance)
# Then import manually:
docker compose exec -T database-api mysql -u root -p"$MYSQL_ROOT_PASSWORD" < dump.sql