How to back up and restore BookStack

What a complete BookStack backup contains

BookStack keeps its data in two places: a MySQL or MariaDB database and a set of folders on disk. A backup that misses either one will not give you your wiki back.

On the LinuxServer image, attachments are in /config/www/files, not /config/files where many people look first. Check your own paths before you rely on a script.

Why the APP_KEY matters

The APP_KEY in .env (or in your Docker environment) is used by BookStack to encrypt certain values. Restore a database without the matching key and anything encrypted with it cannot be read; multi-factor authentication settings are the usual casualty, which means locked-out users. Store a copy of the key securely and separately from the server, for example in your password manager. It is a secret: anyone with the key and a copy of the data has more than they should.

Take the database and files from the same moment

The database refers to image and attachment files by path. If someone uploads a file between your database dump and your file archive, the two no longer match. For a small team the simplest fix is to run both steps back to back at a quiet time. For a move or a planned upgrade, freeze writes first so both describe the same read-only source.

--single-transaction gives a consistent database snapshot without locking InnoDB tables, so BookStack can keep running during the dump. BookHost’s own nightly job goes further: it compares database fingerprints and upload hashes around the backup and falls back to briefly stopping the application if they do not match after three attempts. The restore-testing write-up explains how.

Back up a standard install

Run these on the server, replacing the database name and path with your own. Add -u and -p options, or use a MySQL option file, if your user needs credentials.

# Database dump (use either command)
mysqldump --single-transaction --routines --triggers bookstack > bookstack.sql
mariadb-dump --single-transaction --routines --triggers bookstack > bookstack.sql

# Standard install: configuration, images, attachments and themes
cd /path/to/bookstack
tar -czf bookstack-files.tar.gz .env public/uploads storage/uploads themes

Back up the LinuxServer Docker image

With the LinuxServer image, BookStack and its database run in separate containers. Dump the database from the database container and archive the files from /config/www. Container names and the password variable depend on your compose file; older MariaDB images may only ship mysqldump.

# Database: dump from the database container (name and password variable vary)
docker exec bookstack_db sh -c \
  'exec mariadb-dump --single-transaction --routines --triggers -u root -p"$MYSQL_ROOT_PASSWORD" bookstack' \
  > bookstack.sql

# Files: LinuxServer, run inside the container with /config mounted
tar -czf bookstack-files.tar.gz -C /config/www uploads files .env

Also keep a copy of your docker-compose.yml and any environment file it reads, because that is where APP_KEY, APP_URL and the database settings live.

Check the files before you store them

A backup job that writes an empty dump every night looks just like a working one until you need it. Record checksums and make sure the archive can be read:

sha256sum bookstack.sql bookstack-files.tar.gz > SHA256SUMS
tar -tzf bookstack-files.tar.gz > /dev/null && echo "archive readable"

Then copy the files to a different machine or storage provider, ideally encrypted. The dump contains users, password hashes, roles and settings, so treat it as confidential.

Restore a standard install

Install BookStack as usual on the target server, same version or newer, with an empty database. The files archive contains the old .env, so unpack it first and then correct the database settings and APP_URL for the new server, keeping the old APP_KEY. Do all of this before anyone signs in:

# 1. Unpack files into the BookStack folder. This also restores
#    the old .env, which still points at the old server.
tar -xzf bookstack-files.tar.gz

# 2. Edit .env: keep APP_KEY from the backup, set DB_HOST,
#    DB_DATABASE, DB_USERNAME, DB_PASSWORD and APP_URL for this server
nano .env

# 3. Import the database into the empty BookStack database
mysql -u bookstack -p bookstack < bookstack.sql

# 4. Bring the schema up to the installed version, fix ownership
php artisan migrate
sudo chown -R www-data:www-data public/uploads storage/uploads

# 5. If the address changed
php artisan bookstack:update-url https://old.example.com https://new.example.com

# 6. Rebuild derived data and clear caches
php artisan bookstack:regenerate-search
php artisan bookstack:regenerate-permissions
php artisan cache:clear && php artisan view:clear

Adjust the web server user if it is not www-data. The URL update is only needed when the wiki moves to a new address.

Restore the LinuxServer image

1. Start a fresh database container and create the empty BookStack database.
2. Import the dump with mariadb inside the database container, reading bookstack.sql from standard input.
3. Start the BookStack container with the original APP_KEY and the correct APP_URL, then stop it again once it has created /config/www.
4. Unpack bookstack-files.tar.gz into /config/www so uploads and files land in place.
5. Start the container, read its log for migration errors, and run the search and permission rebuilds shown above if content looks incomplete.

Test your restores

A backup is evidence that something was written, not that you can recover your wiki. Restore into a separate instance on a private network, never over the live one, and check:

• The number of books, chapters and pages matches the live wiki.
• Several recent pages open with the right title and content.
• Images display and attachments download.
• Search finds a page you know exists.
• An administrator and a regular member can both sign in.
• A user with multi-factor authentication can still sign in, a good sign that the APP_KEY is right.
• You wrote down the date, the backup used and the result.

Counts alone do not prove everything is correct, but they catch the most common failure: an empty or partial import. Repeat the test after any change to your backup script, your server or your BookStack version.

How long to keep backups

Keep enough history to notice a problem before its last good copy is gone. A deleted chapter may not be missed for a week or two. A common pattern is daily backups for a couple of weeks plus a few weekly or monthly copies. Balance that against data protection: a backup keeps personal data that was deleted from the wiki, so write down your retention period and delete old copies on schedule.

For comparison, BookHost makes daily backups and removes backups older than seven days at the next daily retention run; with scheduled runs, this can add up to 24 hours. A restore returns the workspace to its last nightly backup, so it can cost up to a day of changes. Backups currently live on the same server as the workspaces; a copy at a second location is in preparation. The reliability page has the details and the dated restore checks.

Moving instead of restoring

The same two artifacts, a database dump and a file archive, are what you need to move BookStack to another server or to managed hosting. If you are considering BookHost, the migration page uses the same dump commands and a tar command that normalises attachment paths, and this field report covers what breaks along the way. If you would rather not run backups at all, see pricing or our self-hosted vs managed comparison.