Skip to content

Upgrading

Upgrade from 1.5.X

Read me first

We often add new features and settings to BunkerWeb. We recommend you read the settings sections of the documentation or the GitHub releases to see what's new.

Procedure

  1. Backup the database:

    • Before proceeding with the database upgrade, ensure to 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.9 users

    If you are using RHEL 8.9 and plan on using an external database, you will need to install the mysql-community-client package to ensure the mysqldump command is available. You can install the package by executing the following commands:

    1. Install the MySQL repository configuration package

      sudo dnf install https://dev.mysql.com/get/mysql80-community-release-el8-9.noarch.rpm

    2. Enable the MySQL repository

      sudo dnf config-manager --enable mysql80-community

    3. Install the MySQL client

      sudo dnf install mysql-community-client

    1. 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"

    2. 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 <database_container> mysqldump -u <username> -p <database_name> > /path/to/backup/directory/backup.sql

    mysqldump -u <username> -p <database_name> > /path/to/backup/directory/backup.sql

    docker exec -it <database_container> pg_dump -U <username> -d <database_name> > /path/to/backup/directory/backup.sql

    pg_dump -U <username> -d <database_name> > /path/to/backup/directory/backup.sql

  2. Upgrade BunkerWeb:

    • Upgrade BunkerWeb to the latest version.

      1. Update the Docker Compose file: Update the Docker Compose file to use the new version of the BunkerWeb image. 

        services:
    bunkerweb:
        image: bunkerity/bunkerweb:1.5.11
        ...
    bw-scheduler:
        image: bunkerity/bunkerweb-scheduler:1.5.11
        ...
    bw-autoconf:
        image: bunkerity/bunkerweb-autoconf:1.5.11
        ...
    bw-ui:
        image: bunkerity/bunkerweb-ui:1.5.11
        ...

      2. Restart the containers: Restart the containers to apply the changes. 

        docker compose down
docker compose up -d

      1. Stop the services: 

        systemctl stop bunkerweb
systemctl stop bunkerweb-ui

      2. Update BunkerWeb:

        First, if you have previously hold the BunkerWeb package, unhold it :

        You can print a list of packages on hold with apt-mark showhold

        sudo apt-mark unhold bunkerweb

        Them, you can update BunkerWeb package :

        sudo apt install -y bunkerweb=1.5.11

        To prevent upgrading BunkerWeb package when executing apt upgrade, you can use the following command :

        sudo apt-mark hold bunkerweb

        More details in the integration Linux page.

        First, if you have previously hold the BunkerWeb package, unhold it :

        You can print a list of packages on hold with dnf versionlock list

        sudo dnf versionlock delete package bunkerweb

        Them, you can update BunkerWeb package :

        sudo dnf install -y bunkerweb-1.5.11

        To prevent upgrading BunkerWeb package when executing dnf upgrade, you can use the following command :

        sudo dnf versionlock add bunkerweb

        More details in the integration Linux page.

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

  4. 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 :

  1. Restore the backup.

    1. Stop the Stack.

      docker compose down

    2. Remove the existing database file.

      docker exec -u 0 -i <scheduler_container> rm -f /var/lib/bunkerweb/db.sqlite3

    3. Restore the backup.

      docker exec -i -T <scheduler_container> sqlite3 /var/lib/bunkerweb/db.sqlite3 < /path/to/backup/directory/backup.sql

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

    1. Stop the Stack.

      docker compose down

    2. Restore the backup.

      docker exec -e MYSQL_PWD=<your_password> -i -T <database_container> mysql -u <username> <database_name> < /path/to/backup/directory/backup.sql

    1. Stop the Stack.

      docker compose down

    2. Remove the existing database.

      docker exec -i <database_container> dropdb -U <username> --force <database_name>

    3. Recreate the database.

      docker exec -i <database_container> createdb -U <username> <database_name>

    4. Restore the backup.

      docker exec -i -T <database_container> psql -U <username> -d <database_name> < /path/to/backup/directory/backup.sql

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

  3. Start the containers.

    docker compose up -d

  1. Stop the services.

    systemctl stop bunkerweb bunkerweb-ui

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

    1. Remove the existing database.

      dropdb -U <username> --force <database_name>

    2. Recreate the database.

      createdb -U <username> <database_name>

    3. Restore the backup.

      psql -U <username> -d <database_name> < /path/to/backup/directory/backup.sql

  3. 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.4.X

Read this if you were a 1.4.X user

A lot of things changed since the 1.4.X releases. Container-based integrations stacks contain more services but, trust us, fundamental principles of BunkerWeb are still there. You will find ready to use boilerplates for various integrations in the misc/integrations folder of the repository.

Scheduler

Back to the 1.4.X releases, jobs (like Let's Encrypt certificate generation/renewal or blacklists download) were executed in the same container as BunkerWeb. For the purpose of separation of concerns, we decided to create a separate service which is now responsible for managing jobs.

Called Scheduler, this service also generates the final configuration used by BunkerWeb and acts as an intermediary between autoconf and BunkerWeb. In other words, the scheduler is the brain of the BunkerWeb 1.5.X stack.

You will find more information about the scheduler here.

Database

BunkerWeb configuration is no more stored in a plain file (located at /etc/nginx/variables.env if you didn't know it). That's it, we now support a fully-featured database as a backend to store settings, cache, custom configs, ... 🥳

Using a real database offers many advantages :

  • Backup of the current configuration
  • Usage with multiple services (scheduler, web UI, ...)
  • Upgrade to a new BunkerWeb version

Please note that we actually support, SQLite, MySQL, MariaDB and PostgreSQL as backends.

You will find more information about the database here.

Redis

When BunkerWeb 1.4.X was used in cluster mode (Swarm or Kubernetes integrations), data were not shared among the nodes. For example, if an attacker was banned via the "bad behavior" feature on a specific node, he could still connect to the other nodes.

Security is not the only reason to have a shared data store for clustered integrations, caching is also another one. We can now store results of time-consuming operations like (reverse) dns lookups so they are available for other nodes.

We actually support Redis as a backend for the shared data store.

See the list of redis settings and the corresponding documentation of your integration for more information.

Default values and new settings

The default value of some settings have changed and we have added many other settings, we recommend you read the security tuning and settings sections of the documentation.