# Snapshot Tool Issues

Installation & Setup Issues
Backup Creation Issues
Restoration Issues
Automation Issues
- Q: Automatic backups are not running
- Q: Automated backups fail but manual backups work
Configuration Issues
- Q: How to change backup storage location after setup?
- Q: How to change backup schedule?
Security & Access Issues
- Q: "Access denied" errors when accessing S3 storage
- Q: SFTP authentication fails
Performance Issues
- Q: Backups take very long to complete
- Q: System becomes slow during backup operations
Monitoring & Maintenance
- Q: How to monitor backup success/failure?
Getting Additional Help

This section covers common problems and solutions when using the PanelAlpha Snapshot Tool for creating, managing, and restoring backups.

# Installation & Setup Issues

# Q: I get "Permission denied" when running snapshot commands

Solution: Always run the snapshot tool with sudo privileges:

sudo ./panelalpha-snapshot.sh --snapshot

The tool requires root access to:

Access Docker containers and volumes
Read/write system configuration files
Create database dumps
Manage file permissions

# Q: Setup wizard fails with "Docker not found" error

Solution: Ensure Docker is installed and running on your system:

# Check if Docker is installed
docker --version

# Start Docker service if not running
sudo systemctl start docker
sudo systemctl enable docker

# Verify Docker is working
sudo docker ps

System Requirements:

Docker version 20.10 or higher
At least 3GB free disk space

# Q: Setup fails with "Repository initialization error"

Solution:

Check storage credentials in your configuration:
```
sudo nano /opt/panelalpha/app/.env-backup
```

Test repository connection:

sudo ./panelalpha-snapshot.sh --test-connection

Common credential issues:
- S3: Verify Access Key ID and Secret Access Key
- SFTP: Check hostname, username, and SSH key permissions
- Local: Ensure target directory exists and has write permissions

# Backup Creation Issues

# Q: Snapshot creation fails with "Database connection error"

Solution:

Verify PanelAlpha is running:

cd /opt/panelalpha/app
docker compose ps

Check database credentials in PanelAlpha's environment file:
```
sudo cat /opt/panelalpha/app/.env | grep DB_
```

Review snapshot logs for specific errors:

sudo tail -f /var/log/panelalpha-snapshot.log

# Q: "Insufficient disk space" error during backup

Solution:

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

Clean up old snapshots to free space:

# List all snapshots
sudo ./panelalpha-snapshot.sh --list-snapups

# Delete specific old snapshots
sudo ./panelalpha-snapshot.sh --delete-snapshots <snapshot-id>

Configure cleanup in .env-backup:
```
BACKUP_RETENTION_DAYS=30
```

# Q: Backup upload to S3/SFTP fails

Solution:

Test network connectivity:

sudo ./panelalpha-snapshot.sh --test-connection

Check credentials and permissions:
- S3: Verify bucket exists and IAM user has write permissions
- SFTP: Ensure SSH key has correct permissions (600) and user can write to target directory

Review connection settings:

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

# Restoration Issues

# Q: Restore fails with "Snapshot not found"

Solution:

Verify snapshot exists:

sudo ./panelalpha-snapshot.sh --list-snapshots

Check repository connection:

sudo ./panelalpha-snapshot.sh --test-connection

Use correct snapshot ID format:

# Correct format (use actual ID from list-snapshots)
sudo ./panelalpha-snapshot.sh --restore a1b2c3d4

# Or restore latest
sudo ./panelalpha-snapshot.sh --restore latest

# Q: After restoration, PanelAlpha doesn't start correctly

Solution:

Check Docker container status:

cd /opt/panelalpha/app
docker compose ps
docker compose logs

Verify database connectivity:

docker compose exec database mysql -u root -p

Restart all services:

cd /opt/panelalpha/app
docker compose down
docker compose up -d

Check file permissions:

sudo chown -R 1000:1000 /opt/panelalpha/app/storage

# Q: Restored instance shows wrong domain/IP addresses

Solution: The restore process should automatically update IP addresses, but if needed:

Update trusted hosts in PanelAlpha admin:
- Go to Admin Area → Configuration → General
- Update Trusted Hosts with new server IP/domain

Clear application cache:

cd /opt/panelalpha/app
docker compose exec api php artisan cache:clear
docker compose exec api php artisan config:clear

# Automation Issues

# Q: Automatic backups are not running

Solution:

Check cron job status:

sudo ./panelalpha-snapshot.sh --cron status

Verify cron service is running:
```
sudo systemctl status cron
```

Check cron logs:

sudo journalctl -u cron -f
sudo tail -f /var/log/panelalpha-snapshot.log

Reinstall automation if needed:

sudo ./panelalpha-snapshot.sh --cron remove
sudo ./panelalpha-snapshot.sh --cron install

# Q: Automated backups fail but manual backups work

Solution:

Check environment variables in cron context:
```
sudo crontab -l
```

Verify log file permissions:

sudo ls -la /var/log/panelalpha-snapshot.log
sudo chmod 644 /var/log/panelalpha-snapshot.log

Test with full paths in cron job:

# Edit crontab to use absolute paths
sudo crontab -e

# Configuration Issues

# Q: How to change backup storage location after setup?

Solution:

Run setup wizard again:
```
sudo ./panelalpha-snapshot.sh --setup
```

Or manually edit configuration:

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

Test new configuration:

sudo ./panelalpha-snapshot.sh --test-connection

# Q: How to change backup schedule?

Solution:

Edit the backup hour setting:

sudo nano /opt/panelalpha/app/.env-backup
# Modify: BACKUP_HOUR=2 (for 2 AM)

Reinstall cron job to apply changes:

sudo ./panelalpha-snapshot.sh --cron remove
sudo ./panelalpha-snapshot.sh --cron install

# Security & Access Issues

# Q: "Access denied" errors when accessing S3 storage

Solution:

Verify IAM permissions for your S3 user:
- s3:ListBucket on the bucket
- s3:GetObject and s3:PutObject on bucket contents
- s3:DeleteObject for cleanup operations

Check AWS credentials:

sudo nano /opt/panelalpha/app/.env-backup
# Verify AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY

Test with AWS CLI (if available):

aws s3 ls s3://your-bucket-name/ --region your-region

# Q: SFTP authentication fails

Solution:

Check SSH key permissions:

sudo chmod 600 /path/to/ssh/key
sudo chown root:root /path/to/ssh/key

Test SSH connection manually:
```
ssh -i /path/to/ssh/key user@hostname
```
Verify user has write permissions on target directory

# Performance Issues

# Q: Backups take very long to complete

Solution:

Check available resources:
```
htop
df -h
iostat -x 1
```
Use incremental backups for large installations:
- Modify backup strategy in configuration
- Keep fewer full backups, more incrementals
Optimize storage location:
- Use local storage for faster initial backup
- Consider faster network connection for remote storage

# Q: System becomes slow during backup operations

Solution:

Schedule backups during low-usage hours:

# Edit backup hour in configuration
sudo nano /opt/panelalpha/app/.env-backup
BACKUP_HOUR=3  # 3 AM

Monitor system resources during backup:
```
sudo iotop
sudo nethogs
```
Consider I/O limits if running on shared infrastructure

# Monitoring & Maintenance

# Q: How to monitor backup success/failure?

Solution:

Check recent backup logs:

sudo tail -f /var/log/panelalpha-snapshot.log

Set up log monitoring with your preferred tool
Create notification scripts that parse log output

Regular health checks:

sudo ./panelalpha-snapshot.sh --cron status
sudo ./panelalpha-snapshot.sh --list-snapshots

# Getting Additional Help

If none of these solutions resolve your issue:

Collect comprehensive logs:

sudo tar -czf snapshot-logs.tar.gz /var/log/panelalpha-snapshot.log /opt/panelalpha/app/.env-backup

Document the issue:
- Exact error messages
- Steps to reproduce
- System information (uname -a, docker --version)
Contact support with detailed information for faster resolution

Prevention is better than cure: Regularly test your backup and restoration process in a staging environment to ensure everything works before you need it in production.