How to Update
Keep your self-hosted Pangolin server up to date with the latest features and security patches
Updating Pangolin is straightforward since it's a collection of Docker images. Simply pull the latest images and restart the stack.
This page covers updating your self-hosted Pangolin server. To update sites and clients, see the respective guides:
Migration Scripts
When Pangolin starts and detects a version update, it runs migration scripts automatically to update your database and configuration files. Pangolin stores the last successfully run version in the database, so it knows which scripts still need to run. Scripts run in order, starting from the oldest unrun script through the latest.
These are commonly SQL schema updates, and sometimes data migrations.
If a release includes a Badger update, Pangolin also tries to update the Traefik config when it still matches the default Pangolin installer Traefik config. If Pangolin cannot apply that change, it fails silently so you can update Badger yourself.
A failed database migration blocks startup and prevents the server from running.
If you are using SQLite, Pangolin automatically creates a copy of the database file before a migration runs so you can roll back if needed. You can disable this by setting the DISABLE_BACKUP_ON_MIGRATION environment variable to true.
Because migrations can change the database schema, downgrading is sometimes impossible and is not recommended. The database may become incompatible with older versions. Always back up your database before updating.
Before You Update
Always backup your data before updating. Copy your config directory to a safe location so you can roll back if needed.
Recommended: Update incrementally between major versions. For example, update from 1.0.0 > 1.1.0 > 1.2.0 instead of jumping directly from 1.0.0 > 1.2.0.
Update Process
Stop the stack
Stop all running containers:
sudo docker compose downCheck latest versions
Find the latest version numbers:
- Pangolin: GitHub Releases
- Gerbil: GitHub Releases
- Traefik: Docker Hub
- Badger: GitHub Releases
Look for the latest stable release (not pre-release or beta versions).
Update version numbers
Edit your docker-compose.yml file and update the image versions:
services:
pangolin:
image: fosrl/pangolin:1.22.0 # Check GitHub Releases for latest version tag
# ... rest of config
gerbil:
image: fosrl/gerbil:1.5.1 # Check GitHub Releases for latest version tag
# ... rest of config
traefik:
image: traefik:v3.7.12 # Check GitHub Releases for latest version tag
# ... rest of configIncrease the Badger version number in config/traefik/traefik_config.yml:
experimental:
plugins:
badger:
moduleName: github.com/fosrl/badger
version: v1.7.0 # Check GitHub Releases for latest version tagUpdate each service you want to upgrade. You can update them individually or all at once.
Pull new images
Download the updated Docker images:
sudo docker compose pullStart the stack
Start the updated containers:
sudo docker compose up -dMonitor the update
Watch the logs to ensure everything starts correctly:
sudo docker compose logs -fVerify functionality
Test that everything is working:
- Access your Pangolin dashboard
- Check that all sites are accessible
- Verify tunnel connections (if using Gerbil)
- Test any custom configurations
If everything works, your update is complete!
Was this page helpful?