Upgrading
Upgrade from 1.6.X
Procedure
Docker
-
Backup the database:
- Before proceeding with the database upgrade, ensure that you perform a complete backup of the current state of the database.
- Use appropriate tools to backup the entire database, including data, schemas, and configurations.
docker exec -it -e BACKUP_DIRECTORY=/path/to/backup/directory <scheduler_container> bwcli plugin backup save
docker cp <scheduler_container>:/path/to/backup/directory /path/to/backup/directory
-
Upgrade BunkerWeb:
-
Upgrade BunkerWeb to the latest version.
-
Update the Docker Compose file: Update the Docker Compose file to use the new version of the BunkerWeb image.
services: bunkerweb: image: bunkerity/bunkerweb:testing ... bw-scheduler: image: bunkerity/bunkerweb-scheduler:testing ... bw-autoconf: image: bunkerity/bunkerweb-autoconf:testing ... bw-ui: image: bunkerity/bunkerweb-ui:testing ...
-
Restart the containers: Restart the containers to apply the changes.
docker compose down docker compose up -d
-
-
-
Check the logs: Check the logs of the scheduler service to ensure that the migration was successful.
docker compose logs <scheduler_container>
-
Verify the database: Verify that the database upgrade was successful by checking the data and configurations in the new database container.
Linux
-
Quick start:
To get started, download the installation script and its checksum, then verify the script's integrity before running it.
LATEST_VERSION=$(curl -s https://api.github.com/repos/bunkerity/bunkerweb/releases/latest | jq -r .tag_name) # Download the script and its checksum wget https://github.com/bunkerity/bunkerweb/releases/download/${LATEST_VERSION}/install-bunkerweb.sh wget https://github.com/bunkerity/bunkerweb/releases/download/${LATEST_VERSION}/install-bunkerweb.sh.sha256 # Verify the checksum sha256sum -c install-bunkerweb.sh.sha256 # If the check is successful, run the script chmod +x install-bunkerweb.sh sudo ./install-bunkerweb.sh
Security Notice
Always verify the integrity of the installation script before running it.
Download the checksum file and use a tool like
sha256sum
to confirm the script has not been altered or tampered with.If the checksum verification fails, do not execute the script—it may be unsafe.
-
How it works:
The same multi‑purpose install script used for fresh installs can also perform an in‑place upgrade. When it detects an existing installation and a different target version, it switches to upgrade mode and applies the following workflow:
- Detection & validation
- Detects OS / version and confirms support matrix.
- Reads currently installed BunkerWeb version from
/usr/share/bunkerweb/VERSION
.
- Upgrade scenario decision
- If the requested version equals the installed one it aborts (unless you explicitly re-run for status).
- If versions differ it flags an upgrade.
- (Optional) Automatic pre‑upgrade backup
- If
bwcli
and the scheduler are available and auto‑backup is enabled, it creates a backup via the built‑in backup plugin. - Destination: either the directory you supplied with
--backup-dir
or a generated path like/var/tmp/bunkerweb-backup-YYYYmmdd-HHMMSS
. - You can disable this with
--no-auto-backup
(manual backup then becomes your responsibility).
- If
- Service quiescing
- Stops
bunkerweb
,bunkerweb-ui
, andbunkerweb-scheduler
to ensure a consistent upgrade (matches the manual procedure recommendations).
- Stops
- Package locks removal
- Temporarily removes
apt-mark hold
/dnf versionlock
onbunkerweb
andnginx
so the targeted version can be installed.
- Temporarily removes
- Upgrade execution
- Installs only the new BunkerWeb package version (NGINX is not reinstalled in upgrade mode unless missing—this avoids touching a correctly pinned NGINX).
- Re‑applies holds/versionlocks to freeze the upgraded versions.
- Finalization & status
- Displays systemd status for core services and next steps.
- Leaves your configuration and database intact—only the application code and managed files are updated.
Key behaviors / notes:
- The script does NOT modify your
/etc/bunkerweb/variables.env
or database content. - If automatic backup failed (or was disabled) you can still do a manual restore using the Rollback section below.
- Upgrade mode intentionally avoids reinstalling or downgrading NGINX outside the supported pinned version already present.
- Logs for troubleshooting remain in
/var/log/bunkerweb/
.
Rollback summary:
- Use the generated backup directory (or your manual backup) + the steps in the Rollback section to restore DB, then reinstall the previous image / package version and re‑lock packages.
- Detection & validation
-
Command-Line Options:
You can drive unattended upgrades with the same flags used for installation. The most relevant for upgrades:
Option Purpose -v, --version <X.Y.Z>
Target BunkerWeb version to upgrade to. -y, --yes
Non‑interactive (assumes upgrade confirmation and enables auto backup unless --no-auto-backup
).--backup-dir <PATH>
Destination for the automatic pre‑upgrade backup. Created if missing. --no-auto-backup
Skip automatic backup (NOT recommended). You must have a manual backup. -q, --quiet
Suppress output (combine with logging / monitoring). -f, --force
Proceed on an otherwise unsupported OS version. --dry-run
Show detected environment, intended actions, then exit without changing anything. Examples:
# Upgrade to testing interactively (will prompt for backup) sudo ./install-bunkerweb.sh --version testing # Non-interactive upgrade with automatic backup to custom directory sudo ./install-bunkerweb.sh -v testing --backup-dir /var/backups/bw-2025-01 -y # Silent unattended upgrade (logs suppressed) – relies on default auto-backup sudo ./install-bunkerweb.sh -v testing -y -q # Perform a dry run (plan) without applying changes sudo ./install-bunkerweb.sh -v testing --dry-run # Upgrade skipping automatic backup (NOT recommended) sudo ./install-bunkerweb.sh -v testing --no-auto-backup -y
Skipping backups
Using
--no-auto-backup
without having a verified manual backup may result in irreversible data loss if the upgrade encounters issues. Always keep at least one recent, tested backup.
-
Backup the database:
- Before proceeding with the database upgrade, ensure that you perform a complete backup of the current state of the database.
- Use appropriate tools to backup the entire database, including data, schemas, and configurations.
Information for Red Hat Enterprise Linux (RHEL) 8.10 users
If you are using RHEL 8.10 and plan on using an external database, you will need to install the
mysql-community-client
package to ensure themysqldump
command is available. You can install the package by executing the following commands:-
Install the MySQL repository configuration package
sudo dnf install https://dev.mysql.com/get/mysql80-community-release-el8-9.noarch.rpm
-
Enable the MySQL repository
sudo dnf config-manager --enable mysql80-community
-
Install the MySQL client
sudo dnf install mysql-community-client
-
Install the PostgreSQL repository configuration package
dnf install "https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-$(uname -m)/pgdg-redhat-repo-latest.noarch.rpm"
-
Install the PostgreSQL client
dnf install postgresql<version>
BACKUP_DIRECTORY=/path/to/backup/directory bwcli plugin backup save
-
Upgrade BunkerWeb:
-
Upgrade BunkerWeb to the latest version.
-
Stop the services:
sudo systemctl stop bunkerweb sudo systemctl stop bunkerweb-ui sudo systemctl stop bunkerweb-scheduler
-
Update BunkerWeb:
First, if you have previously held the BunkerWeb package, unhold it :
You can print a list of packages on hold with
apt-mark showhold
sudo apt-mark unhold bunkerweb nginx
Then, you can update the BunkerWeb package :
sudo apt update && \ sudo apt install -y --allow-downgrades bunkerweb=testing
To prevent the BunkerWeb package from upgrading when executing
apt upgrade
, you can use the following command :sudo apt-mark hold bunkerweb nginx
More details in the integration Linux page.
First, if you have previously held the BunkerWeb package, unhold it :
You can print a list of packages on hold with
dnf versionlock list
sudo dnf versionlock delete package bunkerweb && \ sudo dnf versionlock delete package nginx
Then, you can update the BunkerWeb package :
sudo dnf makecache && \ sudo dnf install -y --allowerasing bunkerweb-testing
To prevent the BunkerWeb package from upgrading when executing
dnf upgrade
, you can use the following command :sudo dnf versionlock add bunkerweb && \ sudo dnf versionlock add nginx
More details in the integration Linux page.
-
Start the services:
Or reboot the system:sudo systemctl start bunkerweb sudo systemctl start bunkerweb-ui sudo systemctl start bunkerweb-scheduler
sudo reboot
-
-
-
Check the logs: Check the logs of the scheduler service to ensure that the migration was successful.
journalctl -u bunkerweb --no-pager
-
Verify the database: Verify that the database upgrade was successful by checking the data and configurations in the new database container.
Rollback
In case of issues
If you encounter any issues during the upgrade, you can rollback to the previous version of the database by restoring the backup taken in step 1.
Get support and more information :
-
Extract the backup if zipped.
Extract the backup zip file first:
unzip /path/to/backup/directory/backup.zip -d /path/to/backup/directory/
-
Restore the backup.
-
Remove the existing database file.
docker exec -u 0 -i <scheduler_container> rm -f /var/lib/bunkerweb/db.sqlite3
-
Restore the backup.
docker exec -i <scheduler_container> sqlite3 /var/lib/bunkerweb/db.sqlite3 < /path/to/backup/directory/backup.sql
-
Fix permissions.
docker exec -u 0 -i <scheduler_container> chown root:nginx /var/lib/bunkerweb/db.sqlite3 docker exec -u 0 -i <scheduler_container> chmod 770 /var/lib/bunkerweb/db.sqlite3
-
Stop the stack.
docker compose down
-
Restore the backup.
docker exec -e MYSQL_PWD=<your_password> -i <database_container> mysql -u <username> <database_name> < /path/to/backup/directory/backup.sql
-
Stop the stack.
docker compose down
-
Remove the existing database.
docker exec -i <database_container> dropdb -U <username> --force <database_name>
-
Recreate the database.
docker exec -i <database_container> createdb -U <username> <database_name>
-
Restore the backup.
docker exec -i <database_container> psql -U <username> -d <database_name> < /path/to/backup/directory/backup.sql
-
Stop the stack.
docker compose down
-
-
Downgrade BunkerWeb.
services: bunkerweb: image: bunkerity/bunkerweb:<old_version> ... bw-scheduler: image: bunkerity/bunkerweb-scheduler:<old_version> ... bw-autoconf: image: bunkerity/bunkerweb-autoconf:<old_version> ... bw-ui: image: bunkerity/bunkerweb-ui:<old_version> ...
-
Start the containers.
docker compose up -d
-
Extract the backup if zipped.
Extract the backup zip file first:
unzip /path/to/backup/directory/backup.zip -d /path/to/backup/directory/
-
Stop the services.
sudo systemctl stop bunkerweb bunkerweb-ui bunkerweb-scheduler
-
Restore the backup.
sudo rm -f /var/lib/bunkerweb/db.sqlite3 sudo sqlite3 /var/lib/bunkerweb/db.sqlite3 < /path/to/backup/directory/backup.sql sudo chown root:nginx /var/lib/bunkerweb/db.sqlite3 sudo chmod 770 /var/lib/bunkerweb/db.sqlite3
mysql -u <username> -p <database_name> < /path/to/backup/directory/backup.sql
-
Remove the existing database.
dropdb -U <username> --force <database_name>
-
Recreate the database.
createdb -U <username> <database_name>
-
Restore the backup.
psql -U <username> -d <database_name> < /path/to/backup/directory/backup.sql
-
-
Start the services.
sudo systemctl start bunkerweb bunkerweb-ui bunkerweb-scheduler
-
Downgrade BunkerWeb.
- Downgrade BunkerWeb to the previous version by following the same steps as when upgrading BunkerWeb in the integration Linux page
Upgrade from 1.5.X
What changed?
Scheduler
Unlike the 1.5.X releases, the Scheduler service no longer uses the docker socket proxy to fetch BunkerWeb's instances. Instead, it uses the new BUNKERWEB_INSTANCES
environment variable.
About the BUNKERWEB_INSTANCES
environment variable
This new variable is a list of BunkerWeb instances separated by spaces in this format: http://bunkerweb:5000 bunkerweb1:5000 bunkerweb2:5000 ...
. The scheduler will then use this list to fetch the instances' configuration and to send the configuration to them.
- The
http://
prefix is optional. - The port is optional and defaults to the value of the
API_HTTP_PORT
environment variable. - The default value of the
BUNKERWEB_INSTANCES
environment variable is127.0.0.1
.
In other words, the new system is fully agnostic and generic: the scheduler is in charge of managing a list of BunkerWeb instances and doesn't need to care about the environment.
Autoconf/Kubernetes/Swarm integrations
If you are using the Autoconf
, Kubernetes
, or Swarm
integrations, you can set the BUNKERWEB_INSTANCES
environment variable to an empty string (so that it doesn't try to send the configuration to the default one which is 127.0.0.1
).
The instances will be automatically fetched by the controller. You can also add custom instances to the list that may not be picked up by the controller.
Since the 1.6
, the Scheduler also have a new built-in healthcheck system, that will check the health of the instances. If an instance becomes unhealthy, the scheduler will stop sending the configuration to it. If the instance becomes healthy again, the scheduler will start sending the configuration to it again.
BunkerWeb container
Another important change is that the settings that were previously declared on the BunkerWeb container are now declared on the scheduler. This means that you'll have to move your settings from the BunkerWeb container to the Scheduler container.
While the settings are now declared on the Scheduler container, you'll still need to declare api related mandatory settings on the BunkerWeb container like the API_WHITELIST_IP
setting which is used to whitelist the Scheduler's IP address, so that it can send the configuration to the instance.
BunkerWeb's container settings
Every API related setting that you declare on the BunkerWeb container have to be mirrored on the Scheduler container so that it keeps working, as the configuration will be overwritten by the Scheduler's generated configuration.
Default values and new settings
We tried our best not to change default value but we have added many other settings. It's highly recommended to read the security tuning and settings sections of the documentation.
Templates
We added a new feature called templates. Templates provide a structured and standardized approach to defining settings and custom configurations, check the concepts/templates section for more information.
Autoconf namespaces
We added a namespace feature to the autoconf integrations. Namespaces allow you to group your instances and apply settings only to them. Check the following sections according to your Integration for more information:
Procedure
-
Backup the database:
- Before proceeding with the database upgrade, ensure that you perform a complete backup of the current state of the database.
- Use appropriate tools to backup the entire database, including data, schemas, and configurations.
docker exec -it -e BACKUP_DIRECTORY=/path/to/backup/directory <scheduler_container> bwcli plugin backup save
docker cp <scheduler_container>:/path/to/backup/directory /path/to/backup/directory
Information for Red Hat Enterprise Linux (RHEL) 8.10 users
If you are using RHEL 8.10 and plan on using an external database, you will need to install the
mysql-community-client
package to ensure themysqldump
command is available. You can install the package by executing the following commands:-
Install the MySQL repository configuration package
sudo dnf install https://dev.mysql.com/get/mysql80-community-release-el8-9.noarch.rpm
-
Enable the MySQL repository
sudo dnf config-manager --enable mysql80-community
-
Install the MySQL client
sudo dnf install mysql-community-client
-
Install the PostgreSQL repository configuration package
dnf install "https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-$(uname -m)/pgdg-redhat-repo-latest.noarch.rpm"
-
Install the PostgreSQL client
dnf install postgresql<version>
BACKUP_DIRECTORY=/path/to/backup/directory bwcli plugin backup save
We first need to install the
sqlite
package in the container.docker exec -u 0 -it <scheduler_container> apk add sqlite
Then, backup the database.
docker exec -it <scheduler_container> sqlite3 /var/lib/bunkerweb/db.sqlite3 ".dump" > /path/to/backup/directory/backup.sql
sqlite3 /var/lib/bunkerweb/db.sqlite3 ".dump" > /path/to/backup/directory/backup.sql
docker exec -it -e MYSQL_PWD=<database_password> <database_container> mariadb-dump -u <username> <database_name> > /path/to/backup/directory/backup.sql
MYSQL_PWD=<database_password> mariadb-dump -u <username> <database_name> > /path/to/backup/directory/backup.sql
docker exec -it -e MYSQL_PWD=<database_password> <database_container> mysqldump -u <username> <database_name> > /path/to/backup/directory/backup.sql
MYSQL_PWD=<database_password> mysqldump -u <username> <database_name> > /path/to/backup/directory/backup.sql
docker exec -it -e PGPASSWORD=<database_password> <database_container> pg_dump -U <username> -d <database_name> > /path/to/backup/directory/backup.sql
PGPASSWORD=<database_password> pg_dump -U <username> -d <database_name> > /path/to/backup/directory/backup.sql
-
Upgrade BunkerWeb:
-
Upgrade BunkerWeb to the latest version.
-
Update the Docker Compose file: Update the Docker Compose file to use the new version of the BunkerWeb image.
services: bunkerweb: image: bunkerity/bunkerweb:testing ... bw-scheduler: image: bunkerity/bunkerweb-scheduler:testing ... bw-autoconf: image: bunkerity/bunkerweb-autoconf:testing ... bw-ui: image: bunkerity/bunkerweb-ui:testing ...
-
Restart the containers: Restart the containers to apply the changes.
docker compose down docker compose up -d
-
Stop the services:
sudo systemctl stop bunkerweb sudo systemctl stop bunkerweb-ui sudo systemctl stop bunkerweb-scheduler
-
Update BunkerWeb:
First, if you have previously held the BunkerWeb package, unhold it :
You can print a list of packages on hold with
apt-mark showhold
sudo apt-mark unhold bunkerweb nginx
Then, you can update the BunkerWeb package :
sudo apt update && \ sudo apt install -y --allow-downgrades bunkerweb=testing
To prevent the BunkerWeb package from upgrading when executing
apt upgrade
, you can use the following command :sudo apt-mark hold bunkerweb nginx
More details in the integration Linux page.
First, if you have previously held the BunkerWeb package, unhold it :
You can print a list of packages on hold with
dnf versionlock list
sudo dnf versionlock delete package bunkerweb && \ sudo dnf versionlock delete package nginx
Then, you can update the BunkerWeb package :
sudo dnf makecache && \ sudo dnf install -y --allowerasing bunkerweb-testing
To prevent the BunkerWeb package from upgrading when executing
dnf upgrade
, you can use the following command :sudo dnf versionlock add bunkerweb && \ sudo dnf versionlock add nginx
More details in the integration Linux page.
-
Start the services:
Or reboot the system:sudo systemctl start bunkerweb sudo systemctl start bunkerweb-ui sudo systemctl start bunkerweb-scheduler
sudo reboot
-
-
-
Check the logs: Check the logs of the scheduler service to ensure that the migration was successful.
docker compose logs <scheduler_container>
journalctl -u bunkerweb --no-pager
-
Verify the database: Verify that the database upgrade was successful by checking the data and configurations in the new database container.
Rollback
In case of issues
If you encounter any issues during the upgrade, you can rollback to the previous version of the database by restoring the backup taken in step 1.
Get support and more information :
-
Extract the backup if zipped.
Extract the backup zip file first:
unzip /path/to/backup/directory/backup.zip -d /path/to/backup/directory/
-
Restore the backup.
-
Remove the existing database file.
docker exec -u 0 -i <scheduler_container> rm -f /var/lib/bunkerweb/db.sqlite3
-
Restore the backup.
docker exec -i <scheduler_container> sqlite3 /var/lib/bunkerweb/db.sqlite3 < /path/to/backup/directory/backup.sql
-
Fix permissions.
docker exec -u 0 -i <scheduler_container> chown root:nginx /var/lib/bunkerweb/db.sqlite3 docker exec -u 0 -i <scheduler_container> chmod 770 /var/lib/bunkerweb/db.sqlite3
-
Stop the stack.
docker compose down
-
Restore the backup.
docker exec -e MYSQL_PWD=<your_password> -i <database_container> mysql -u <username> <database_name> < /path/to/backup/directory/backup.sql
-
Stop the stack.
docker compose down
-
Remove the existing database.
docker exec -i <database_container> dropdb -U <username> --force <database_name>
-
Recreate the database.
docker exec -i <database_container> createdb -U <username> <database_name>
-
Restore the backup.
docker exec -i <database_container> psql -U <username> -d <database_name> < /path/to/backup/directory/backup.sql
-
Stop the stack.
docker compose down
-
-
Downgrade BunkerWeb.
services: bunkerweb: image: bunkerity/bunkerweb:<old_version> ... bw-scheduler: image: bunkerity/bunkerweb-scheduler:<old_version> ... bw-autoconf: image: bunkerity/bunkerweb-autoconf:<old_version> ... bw-ui: image: bunkerity/bunkerweb-ui:<old_version> ...
-
Start the containers.
docker compose up -d
-
Extract the backup if zipped.
Extract the backup zip file first:
unzip /path/to/backup/directory/backup.zip -d /path/to/backup/directory/
-
Stop the services.
sudo systemctl stop bunkerweb bunkerweb-ui bunkerweb-scheduler
-
Restore the backup.
sudo rm -f /var/lib/bunkerweb/db.sqlite3 sudo sqlite3 /var/lib/bunkerweb/db.sqlite3 < /path/to/backup/directory/backup.sql sudo chown root:nginx /var/lib/bunkerweb/db.sqlite3 sudo chmod 770 /var/lib/bunkerweb/db.sqlite3
mysql -u <username> -p <database_name> < /path/to/backup/directory/backup.sql
-
Remove the existing database.
dropdb -U <username> --force <database_name>
-
Recreate the database.
createdb -U <username> <database_name>
-
Restore the backup.
psql -U <username> -d <database_name> < /path/to/backup/directory/backup.sql
-
-
Start the services.
sudo systemctl start bunkerweb bunkerweb-ui bunkerweb-scheduler
-
Downgrade BunkerWeb.
- Downgrade BunkerWeb to the previous version by following the same steps as when upgrading BunkerWeb in the integration Linux page