PanelAlpha Documentation
Back Home
Live Demo Get Started

Snapshot Tool Issues

Documentation

    # Snapshot Tool Issues

    • Installation & Setup Issues
      • Permission Denied When Running Snapshot Commands
      • Setup Wizard Fails with "Docker Not Found" Error
      • Setup Fails with "Repository Initialization Error"
    • Backup Creation Issues
      • Snapshot Creation Fails with "Database Connection Error"
      • "Insufficient Disk Space" Error During Backup
      • Backup Upload to S3/SFTP Fails
    • Restoration Issues
      • Restore Fails with "Snapshot Not Found"
      • After Restoration, PanelAlpha Does Not Start Correctly
      • Restored Instance Shows Wrong Domain/IP Addresses
    • Automation Issues
      • Automatic Backups Are Not Running
      • Automated Backups Fail but Manual Backups Work
    • Configuration Issues
      • How to Change Backup Storage Location After Setup
      • How to Change Backup Schedule
    • Security & Access Issues
      • "Access Denied" Errors When Accessing S3 Storage
      • SFTP Authentication Fails
    • Performance Issues
      • Backups Take Too Long to Complete
      • System Becomes Slow During Backup Operations
    • Monitoring & Maintenance
      • How to Monitor Backup Success or Failure
    • Getting Additional Help

    This section covers common problems and solutions when using the PanelAlpha Snapshot Tool to create, manage, and restore backups.

    # Installation & Setup Issues

    # Permission Denied When Running Snapshot Commands

    Problem: You receive a "Permission denied" error when running snapshot commands.

    Solution: Always run the snapshot tool with sudo:

    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

    # Setup Wizard Fails with "Docker Not Found" Error

    Problem: The setup wizard fails because Docker is not found.

    Solution: Ensure Docker is installed and running:

    # 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 3 GB free disk space

    # Setup Fails with "Repository Initialization Error"

    Problem: The setup fails with a repository initialization error.

    Solution:

    1. Check storage credentials in your configuration:
      sudo nano /opt/panelalpha/app/.env-backup
    2. Test the repository connection:
      sudo ./panelalpha-snapshot.sh --test-connection
    3. Verify credentials for your storage type:
      • S3: Verify Access Key ID and Secret Access Key
      • SFTP: Check hostname, username, and SSH key permissions
      • Local: Ensure the target directory exists and has write permissions

    # Backup Creation Issues

    # Snapshot Creation Fails with "Database Connection Error"

    Problem: Snapshot creation fails with a 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

    # "Insufficient Disk Space" Error During Backup

    Problem: Backup fails due to insufficient disk space.

    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-snapshots

# Delete specific old snapshots
sudo ./panelalpha-snapshot.sh --delete-snapshots <snapshot-id>
    3. Configure cleanup in .env-backup:
      BACKUP_RETENTION_DAYS=30

    # Backup Upload to S3/SFTP Fails

    Problem: Backup upload to remote storage fails.

    Solution:

    1. Test network connectivity:
      sudo ./panelalpha-snapshot.sh --test-connection
    2. Check credentials and permissions:
      • S3: Verify the bucket exists and the IAM user has write permissions
      • SFTP: Ensure the SSH key has correct permissions (600) and the user can write to the target directory
    3. Review connection settings:
      sudo nano /opt/panelalpha/app/.env-backup

    # Restoration Issues

    # Restore Fails with "Snapshot Not Found"

    Problem: The restore process cannot find the specified snapshot.

    Solution:

    1. Verify the snapshot exists:
      sudo ./panelalpha-snapshot.sh --list-snapshots
    2. Check the repository connection:
      sudo ./panelalpha-snapshot.sh --test-connection
    3. Use the 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

    # After Restoration, PanelAlpha Does Not Start Correctly

    Problem: PanelAlpha does not start correctly after a restore.

    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

    # Restored Instance Shows Wrong Domain/IP Addresses

    Problem: The restored instance shows incorrect domain or IP addresses.

    Solution: The restore process should automatically update IP addresses. If needed:

    1. Update trusted hosts in PanelAlpha admin:
      • Go to Admin Area → Configuration → General
      • Update Trusted Hosts with the new server IP or domain
    2. Clear the application cache:
      cd /opt/panelalpha/app
docker compose exec api php artisan cache:clear
docker compose exec api php artisan config:clear

    # Automation Issues

    # Automatic Backups Are Not Running

    Problem: Scheduled automatic backups are not running.

    Solution:

    1. Check cron job status:
      sudo ./panelalpha-snapshot.sh --cron status
    2. Verify the 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

    # Automated Backups Fail but Manual Backups Work

    Problem: Automated backups fail while manual backups succeed.

    Solution:

    1. Check environment variables in the 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 the cron job:
      sudo crontab -e

    # Configuration Issues

    # How to Change Backup Storage Location After Setup

    Problem: You need to change the backup storage location after initial setup.

    Solution:

    1. Run the setup wizard again:
      sudo ./panelalpha-snapshot.sh --setup
    2. Or manually edit the configuration:
      sudo nano /opt/panelalpha/app/.env-backup
    3. Test the new configuration:
      sudo ./panelalpha-snapshot.sh --test-connection

    # How to Change Backup Schedule

    Problem: You need to change the 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 the cron job to apply changes:
      sudo ./panelalpha-snapshot.sh --cron remove
sudo ./panelalpha-snapshot.sh --cron install

    # Security & Access Issues

    # "Access Denied" Errors When Accessing S3 Storage

    Problem: You receive "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

    # SFTP Authentication Fails

    Problem: SFTP authentication fails during backup operations.

    Solution:

    1. Check SSH key permissions:
      sudo chmod 600 /path/to/ssh/key
sudo chown root:root /path/to/ssh/key
    2. Test the SSH connection manually:
      ssh -i /path/to/ssh/key user@hostname
    3. Verify the user has write permissions on the target directory.

    # Performance Issues

    # Backups Take Too Long to Complete

    Problem: Backups take an excessive amount of time to complete.

    Solution:

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

    # System Becomes Slow During Backup Operations

    Problem: The system slows down significantly during backups.

    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

    # How to Monitor Backup Success or Failure

    Problem: You need to monitor whether backups succeed or fail.

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