PanelAlpha Documentation
Back Home
Live Demo Get Started

Snapshot Tool Issues

Documentation

    # Snapshot Tool Issues

    • Installation & Setup Issues
      • Q: I get "Permission denied" when running snapshot commands
      • Q: Setup wizard fails with "Docker not found" error
      • Q: Setup fails with "Repository initialization error"
    • Backup Creation Issues
      • Q: Snapshot creation fails with "Database connection error"
      • Q: "Insufficient disk space" error during backup
      • Q: Backup upload to S3/SFTP fails
    • Restoration Issues
      • Q: Restore fails with "Snapshot not found"
      • Q: After restoration, PanelAlpha doesn't start correctly
      • Q: Restored instance shows wrong domain/IP addresses
    • 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:

    1. Check storage credentials in your configuration:

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

    2. Test repository connection:

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

    3. 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:

    1. Verify PanelAlpha is running:

      cd /opt/panelalpha/app
docker compose ps

    2. Check database credentials in PanelAlpha's environment file:

      sudo cat /opt/panelalpha/app/.env | grep DB_

    3. Review snapshot logs for specific errors:

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

    # Q: "Insufficient disk space" error during backup

    Solution:

    1. Check available space:

      df -h /var/tmp
df -h /opt/panelalpha

    2. 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>

    3. Configure cleanup in .env-backup:

      BACKUP_RETENTION_DAYS=30

    # Q: Backup upload to S3/SFTP fails

    Solution:

    1. Test network connectivity:

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

    2. 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

    3. Review connection settings:

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

    # Restoration Issues

    # Q: Restore fails with "Snapshot not found"

    Solution:

    1. Verify snapshot exists:

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

    2. Check repository connection:

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

    3. 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:

    1. Check Docker container status:

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

    2. Verify database connectivity:

      docker compose exec database mysql -u root -p

    3. Restart all services:

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

    4. 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:

    1. Update trusted hosts in PanelAlpha admin:

      • Go to Admin Area → Configuration → General
      • Update Trusted Hosts with new server IP/domain

    2. 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:

    1. Check cron job status:

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

    2. Verify cron service is running:

      sudo systemctl status cron

    3. Check cron logs:

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

    4. 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:

    1. Check environment variables in cron context:

      sudo crontab -l

    2. Verify log file permissions:

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

    3. 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:

    1. Run setup wizard again:

      sudo ./panelalpha-snapshot.sh --setup

    2. Or manually edit configuration:

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

    3. Test new configuration:

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

    # Q: How to change backup schedule?

    Solution:

    1. Edit the backup hour setting:

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

    2. 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:

    1. 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

    2. Check AWS credentials:

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

    3. Test with AWS CLI (if available):

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

    # Q: SFTP authentication fails

    Solution:

    1. Check SSH key permissions:

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

    2. Test SSH connection manually:

      ssh -i /path/to/ssh/key user@hostname

    3. Verify user has write permissions on target directory

    # Performance Issues

    # Q: Backups take very long to complete

    Solution:

    1. Check available resources:

      htop
df -h
iostat -x 1

    2. Use incremental backups for large installations:

      • Modify backup strategy in configuration
      • Keep fewer full backups, more incrementals

    3. 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:

    1. Schedule backups during low-usage hours:

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

    2. Monitor system resources during backup:

      sudo iotop
sudo nethogs

    3. Consider I/O limits if running on shared infrastructure

    # Monitoring & Maintenance

    # Q: How to monitor backup success/failure?

    Solution:

    1. Check recent backup logs:

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

    2. Set up log monitoring with your preferred tool

    3. Create notification scripts that parse log output

    4. 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:

    1. Collect comprehensive logs:

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

    2. Document the issue:

      • Exact error messages
      • Steps to reproduce
      • System information (uname -a, docker --version)

    3. 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.