Backup + Migration

Not tested yet!
❓ I installed BookStack via Docker (as in the guide). Could you please explain how to create backups (full content backup) so that I can migrate the website if needed, e.g., to another server/domain? Here is BookStack’s official guide.
Full BookStack backup (Docker) – so that a move to another server/domain works 🧰📦
For a complete, restorable backup, you essentially need two components:
Database (all pages, books, users, permissions, settings …)
Files/config (uploads, attachments, 
.env/APP_KEY, possibly themes/modules)
Since you have the setup like in your guide (
/opt/bookstack with 
docker-compose.yml, volumes 
./mariadb and 
./bookstack), this is pleasantly simple.
✅ What exactly needs to be backed up?
1) Database (MariaDB)
The content is in the DB container, and in your setup it’s persisted under:
./mariadb (as volume 
./mariadb:/config)
Cleanest approach: SQL dump (portable, tolerant across versions)
2) Files (BookStack container volume)
Persistent data is located under:
./bookstack (as volume 
./bookstack:/config)
In it, especially important:
.env (including APP_KEY!)
uploads/attachments
possibly 
www/themes/custom/... (your hacks/modules)
3) Compose/Caddy (helpful for migration)
docker-compose.yml
Caddyfile
Caddy data optional:
./caddy/data & 
./caddy/config (certificates/state).
Not strictly required, but sometimes saves re-issuing/rate limits.
🗂️ Create a backup (recommended approach)
Assumption: project is located in 
/opt/bookstack and the containers are named as in your YAML:
bookstack-mariadb and 
bookstack.
Step 1: Create a backup folder
cd /opt/bookstack
mkdir -p backups
Step 2: Dump the database as SQL 💾
docker exec -i bookstack-mariadb \
  mysqldump -u bookstack -pbookstack \
  --single-transaction --routines --triggers \
  bookstack > backups/bookstack-db-$(date +%F).sql
Important: Replace 
-pbookstack with your real password (from 
MYSQL_PASSWORD).
Alternative (safer because the password won’t end up in shell history):
Omit 
-p..., then 
mysqldump will prompt interactively for the password:
docker exec -it bookstack-mariadb mysqldump -u bookstack -p --single-transaction --routines --triggers bookstack > backups/bookstack-db-$(date +%F).sql
Step 3: Archive files/volumes 📦
tar -czvf backups/bookstack-files-$(date +%F).tar.gz \
  docker-compose.yml Caddyfile \
  bookstack mariadb caddy
If you don’t want to back up Caddy, you can do it leaner:
tar -czvf backups/bookstack-files-$(date +%F).tar.gz \
  docker-compose.yml Caddyfile \
  bookstack mariadb
Step 4: (Optional) Integrity check ✅
ls -lh backups/
head -n 5 backups/bookstack-db-*.sql
tar -tzf backups/bookstack-files-*.tar.gz | head
🔁 Restore (on a new server) – incl. domain/URL migration
Step 0: Prerequisites
Docker + Docker Compose installed
DNS of the new domain points to the new server (for HTTPS via Caddy)
Step 1: Copy the backup over
Pack on the old server or copy directly:
scp -r /opt/bookstack/backups user@new-server:/opt/bookstack/
Step 2: Restore files (Compose/volumes) 📂
On the new server:
cd /opt/bookstack
tar -xvzf backups/bookstack-files-YYYY-MM-DD.tar.gz
(Adjust the date, of course.)
Step 3: Start containers (DB should already be running) 🐳
cd /opt/bookstack
docker compose up -d mariadb
Wait a few seconds until MariaDB is ready.
Step 4: Import the database 🧩
cat backups/bookstack-db-YYYY-MM-DD.sql | \
  docker exec -i bookstack-mariadb mysql -u bookstack -pbookstack bookstack
Again: adjust the password or use interactive mode.
Step 5: Start BookStack
docker compose up -d
🌍 Domain/URL changed? (very important!)
If you move to a different URL/domain, you must:
1) Adjust 
APP_URL in the 
.env
In your volume, the 
.env is typically located at:
./bookstack/www/.env (common with linuxserver/bookstack)
or 
./bookstack/.env (depending on image/setup)
Find it like this:
find /opt/bookstack/bookstack -maxdepth 3 -name ".env" -print
Then set 
APP_URL=
https://new-domain.tld.
Pay attention: The 
APP_KEY must remain the old one (otherwise encrypted data will break, e.g., MFA secrets).
2) BookStack command: “Update System URL”
So that content/links in the DB are rewritten cleanly:
docker exec -it bookstack php /app/www/artisan bookstack:update-url https://old-domain.tld https://new-domain.tld
(If the path in the container is different, this often also works: 
php artisan ... from 
/app/www.)
🧠 Practical notes (so it’s truly “migration-safe”)
Always store backups offsite (another system/storage).
Database dump + file archive is the most portable.
If you restore to a newer BookStack version:
Restore DB
Bring containers up
Then run migrations (if needed):
docker exec -it bookstack php /app/www/artisan migrate --force
If you want: I’ll make you a “one-command backup script” 🧾
Just tell me briefly:
Is your 
.env located at 
bookstack/www/.env?
What are your containers actually named (
docker ps output)?
Do you want to back up Caddy certificates or preferably not?
Then I’ll give you a small script including rotation (e.g., “keep the last 7 backups”) and optional upload to S3/Hetzner Storage Box.