Updating PegaProx
Update Sources:
Primary: github.com/PegaProx/project-pegaprox
Mirror: updates.pegaprox.com
Option 1: Update Script (Recommended)
cd /opt/PegaProx
curl -O https://raw.githubusercontent.com/PegaProx/project-pegaprox/refs/heads/main/update.sh
chmod +x update.sh
sudo ./update.sh
The update script downloads the latest release archive from GitHub (with a mirror fallback to updates.pegaprox.com), verifies the SHA256 checksum, extracts files, and restarts the service.
Option 2: Web UI
Go to Settings → Updates and click "Check for Updates". If an update is available, click "Install Update". The server will restart automatically.
The update dialog lists the behaviour changes of the new release before you install it. Read them, especially on a multi-tenant install: a release can take something away from an existing setup on purpose (for example a permission that is now enforced). Before the update to 1.5, read Upgrading to 1.5: its first start encrypts the database on more kinds of install.
From 1.3, the restart button, an update and a rollback restart PegaProx in place. Under systemd they restart the pegaprox service only when this process really runs as that service; otherwise PegaProx restarts itself.
PegaProx High Availability
In a PegaProx group, run the same release on every member. A member on another release skips configuration columns it does not know and says so in its sync status.
Option 3: Git Pull
cd /opt/PegaProx
git pull origin main
pip install -r requirements.txt
sudo systemctl restart pegaprox
In a git checkout, the bundled plugins' config.json files are part of the repository. git pull keeps the settings you changed there. When a release changes the defaults of a plugin whose settings you changed, git pull stops and names the file (Your local changes to the following files would be overwritten by merge). Put your settings aside, pull, and put them back:
cp plugins/status_page/config.json /root/status_page.config.json
git checkout -- plugins/status_page/config.json
git pull origin main
cp /root/status_page.config.json plugins/status_page/config.json
Plugins and their settings
Every way of updating brings the bundled plugins of the new release and keeps what you set: a plugin's code and pages are replaced, its config.json stays as it is, and a plugin you added yourself is not touched. Where the plugins live on each kind of install: Plugin System.
| Update | What happens to the plugins |
|---|---|
apt upgrade (also the VM and LXC appliances) |
The package brings them from /usr/share/pegaprox/plugins into /var/lib/pegaprox/plugins. |
| Docker image pull | The new container brings them from the image into /app/config/plugins in the config volume when it starts. |
update.sh, in-app updater |
They come with the release archive into the install's plugins/ folder. |
git pull |
Git updates the checkout's plugins/ folder, see above. |
This is so from 1.4.0. Older Docker images, update.sh and in-app updates put each plugin's config.json back to the defaults, and the update to that release is still done by the old updater: fetch the new update.sh first as shown in Option 1, or copy the plugins aside before an in-app update (cp -a /opt/PegaProx/plugins /root/plugins-before-update) and put each plugin's config.json back afterwards. For a Docker install, see the note on the plugin page.
Update Process Details
| Priority | Source | Method |
|---|---|---|
| Primary | GitHub | Archive download (project-pegaprox-main.tar.gz) |
| Fallback | Mirror | updates.pegaprox.com/archive/main.tar.gz |
| Last resort | Mirror | Individual file download (every file listed in version.json) |
Backup Before Update
Automatic backup to backups/backup_{version}_{date}/ of: entry point, backend package, frontend, version.json, requirements.txt.
bash
# Force re-download even if already on latest version
sudo bash update.sh --force
Note: File ownership is preserved during updates. Uses rsync with tar-based fallback for minimal installations.
Going back to an older release
Before you go back, read the upgrade page of the release you leave. For 1.5 the steps are in Upgrading to 1.5.
From 1.5, the first start encrypts the database on more kinds of install, and 1.4.1 opens an encrypted database only while SQLCipher is installed. On the Debian package, mark the SQLCipher packages as installed by hand before the downgrade, so that apt does not remove them as no longer needed (for example in apt autoremove):
sudo apt-mark manual python3-sqlcipher3 libsqlcipher1 sqlcipher
The start that encrypts the database leaves a plain copy of it in the config directory, pegaprox.db.plain.bak.<timestamp>. It is a way back to the state before the update for one hour only: the first start an hour or more later shreds it (PEGAPROX_PLAIN_BACKUP_RETENTION_S changes the window). After that, the way back is the backup you took before updating.