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.7
              ...
          bw-scheduler:
              image: bunkerity/bunkerweb-scheduler:1.5.7
              ...
          bw-autoconf:
              image: bunkerity/bunkerweb-autoconf:1.5.7
              ...
          bw-ui:
              image: bunkerity/bunkerweb-ui:1.5.7
              ...
      

    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:

  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. Remove the existing database file.

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

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

      docker compose down <scheduler_container>
      
    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 Scheduler container.

      docker compose down <scheduler_container>
      
    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. Restart the containers.

    docker compose down
    docker compose up -d
    
  1. Stop the services.

    systemctl stop bunkerweb
    systemctl stop bunkerweb-ui
    
  2. Restore the backup.

    rm -f /var/lib/bunkerweb/db.sqlite3
    sqlite3 /var/lib/bunkerweb/db.sqlite3 < /path/to/backup/directory/backup.sql
    
    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.