Backup before upgrade

This describes how to backup BookStack once at a time and manually. It is recommended to automate this procedure to save time. You can find the complete script here.

Explore our MySQL instance

If you don't remember much about the database you have setup months ago and haven't bothered to write any documentation whatsoever like me, don't worry, we can fix that. All you need to know is the password of MariaDB/MySQL root user. I fortunately do remember mine. Type the following to access MySQL on localhost with the root user and don't forget to run the command as root, otherwise it won't work (you need elevated privileges in the terminal to access MySQL with the root user):

$ sudo mysql -u root -p

You can type your password directly after the -p flag, but that is considered a bad practice. It's much safer to leave it empty. If you do so, it will ask you to supply password after the initial command like this (password will be hidden):

Enter password: **************

Afterwards, you will see a welcome screen:

Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 9385
Server version: 10.3.29-MariaDB-0+deb10u1 Debian 10

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]>

List all databases:

MariaDB> SHOW DATABASES;

You should see all databases present on the server:

+--------------------+
| Database           |
+--------------------+
| bookstack_db       |
| information_schema |
| mysql              |
| performance_schema |
+--------------------+
4 rows in set (0.005 sec)

To see all users registered with MySQL, type the following (MySQL is not case sensitive, the words in CAPS are there just for better visibility):

MariaDB> SELECT host,user,password FROM mysql.user;

There should be your BookStack Administrator:

+-----------+------------------+-------------------------------------------+
| host      | user             | password                                  |
+-----------+------------------+-------------------------------------------+
| localhost | root             | *A0ACFB4651HGIU4651456DGG48156E7E709FFD72 |
| localhost | bs-administrator | *A856FBFU57631GAHLOUG8461T48648GSHGHF4773 |
+-----------+------------------+-------------------------------------------+
2 rows in set (0.000 sec)

Now exit the MySQL db engine and finally get to the backup.

MariaDB> quit;
Bye

Backup the BookStack database

Use the BookStack database administrator (the one who has privileges on the BookStack database) to create a dump (backup) file of the BookStack database (get the name of user and database from previous steps):

$ mysqldump -u bs-administrator -p bookstack_db > /home/user/bookstack_backup.sql

and enter password:

Enter password: *************

The command mysqldump will use a user bs-administrator to backup a database bookstack_db to the home directory of your user (replace with your username) under the name bookstack_backup.sql

Check if the file was created in your home directory with ls -lah ~ and you are good to go.

Backup Webserver Data

BookStack data will most likely be stored in the /var/www directory, in my case in /var/www/BookStack. Within this folder, it is only required to backup public/uploads, storage/uploads (all uploaded images on the website) and .env file which contains all configuration, including database settings like user and password. Keep this file well protected. The other option is to backup the entire /var/www/BookStack directory, but only the files and folders above are non-restorable. I prefer having the entire directory backed up, so I can copy it back in case something breaks.

$ sudo tar -czvf /home/user/BookStack_files_backup.tar.gz /var/www/BookStack

Because of how I have configured permissions in /var/www/BookStack, I need to run the command above as root, you may not need to. Tar creates an archive from /var/www/BookStack (-c flag), compresses it with gzip (-z), shows what files are being archived (-v as verbose) and names it BookStack_files_backup.tar.gz and saves it in my home directory.

tar preserves file permissions and ownership when archiving by default. Howerver, to extract an archive with the same permissions and ownerships, you have to run tar as root when extracting. Also research the -p flag to learn more.

BookStack should be now fully backed up in case something goes wrong during the update.