https://asciinema.org/a/QnoybaFPNxmZsIhu1LsY7kbsT
Watch the above Video before deploying the script.
Introduction
Welcome to the guide for using the Pangolin Stack Management Script. This tool helps you manage your Pangolin deployment by providing robust backup, update, and restore capabilities. Whether you’re updating to the latest versions or need to roll back to a previous state, this script makes the process straightforward and safe.
System Requirements
Before you begin using the script, ensure your system meets these requirements:
- Docker Engine (version 20.10.0 or higher)
- Docker Compose V2
- Bash shell environment
- Standard Unix utilities (grep, sed, awk)
- At least 1GB of free disk space for backups
- Read/write permissions in the script’s directory
Installation
Setting up the script is straightforward:
- Save the script to your Pangolin project directory:
wget https://gist.githubusercontent.com/hhftechnology/96bc511034a20ae081139bd2306906bf/raw/5bddbbf349920e7df456c5b6b0bdf952d8fe0e11/update-stack.sh -O update-stack.sh
- Make it executable:
chmod +x update-stack.sh
Core Features
The script provides two main functions:
- Update Mode: Safely updates your services to new versions while creating backups
- Restore Mode: Returns your stack to a previous working state
Each operation includes built-in safety checks and comprehensive logging.
Updating Your Stack
To update your Pangolin stack, follow these steps:
- Start the update process:
./update-stack.sh update
- You’ll see your current versions displayed:
Current versions:
------------------------
Current Pangolin tag: 1.0.0-beta.9
Current Gerbil tag: 1.0.0-beta.3
Current Traefik tag: v3.1
-
For each service, you can:
- Press Enter to keep the current version
- Type a new version number to upgrade/downgrade
-
Review the summary of changes:
Summary of changes:
------------------------
Pangolin: 1.0.0-beta.9 -> 1.0.0-beta.10
Gerbil: 1.0.0-beta.3 -> 1.0.0-beta.3
Traefik: v3.1 -> v3.2
------------------------
- Confirm the changes by typing ‘y’ when prompted
During the update, the script will:
- Create a timestamped backup
- Safely stop all services
- Update the specified versions
- Restart the stack
- Verify all services are running properly
Restoring Your Stack
You have two options for restoration:
- Restore to the most recent backup:
./update-stack.sh restore
- Restore to a specific backup:
./update-stack.sh restore ./backups/20250205_062549
The restoration process:
- Validates the backup’s integrity
- Gracefully stops current services
- Restores configuration files
- Restarts the stack with the backup’s settings
- Verifies service health
Understanding Backups
Each backup is stored in the ./backups directory with a timestamp format (e.g., 20250205_062549). A backup contains:
docker-compose.yml: The complete stack configurationconfig/: All configuration filesupdate.log: Detailed operation logsold_tags.txt: Record of service versions
Best Practices
To get the most out of the script, follow these guidelines:
Before Updates
- Review release notes for the new versions
- Test updates in a non-production environment first
- Ensure you have enough disk space for backups
- Document any custom configurations
During Operations
- Never interrupt the script during execution
- Monitor the logs for any warnings or errors
- Wait for the final verification step to complete
Backup Management
- Keep at least three recent backups
- Regularly test restore operations
- Clean up old backups periodically
- Store critical backups in a separate location
Troubleshooting Guide
If you encounter issues, follow these steps:
Update Failed
- Check the logs in
./backups/[timestamp]/update.log - Verify Docker has enough resources
- Ensure all image versions exist in the registry
- Try restoring to the previous state
Restore Failed
- Verify the backup directory exists and is complete
- Check file permissions
- Ensure enough disk space is available
- Review service logs:
docker compose logs
Common Error Solutions:
# If services won't start
docker compose logs
# If permission errors occur
sudo chown -R $(id -u):$(id -g) ./backups
# If cleanup is needed
docker system prune
Maintenance Tasks
Regular maintenance helps keep your system healthy:
Clean Old Backups
# Remove backups older than 30 days
find ./backups -type d -mtime +30 -exec rm -rf {} +
Remove Unused Images
# Clean up old Docker images
docker image prune -a --filter "until=168h"
Verify Backup Integrity
# List and check recent backups
ls -ltr ./backups/
./update-stack.sh restore ./backups/[timestamp] # Test restore
Logging and Monitoring
The script maintains detailed logs of all operations:
- Update Logs:
./backups/[timestamp]/update.log - Restore Logs:
/tmp/restore_[pid].log
Monitor these logs for:
- Service state changes
- Error messages
- Version changes
- Operation timing
Security Considerations
The script includes several security features:
- Validates input parameters
- Uses secure file permissions
- Implements graceful shutdowns
- Maintains operation logs
- Verifies service health
Conclusion
This script simplifies managing your Pangolin stack while maintaining system reliability and safety. Regular backups and careful version management will help ensure your deployment remains stable and secure.
For additional help or to report issues, please refer to the project’s documentation or contact support.
Remember: Always test updates in a safe environment first, and maintain good backup practices for peace of mind.
