Skip to main content

Backup + Migration

❓ IIch installedhabe BookStack viaper Docker installiert (aswie in theder guideAnleitung). CouldKannst youdu pleasemir explainbitte howerklären, towie createich backupsBackups erstelle (avollständige complete content backup) so that I can migrate the website if needed, e.g.Inhaltssicherung), tosodass anotherich server/domain?die Website bei Bedarf z.B. zu einem anderen Server/Domain umziehen kann? HereHier isist BookStack’sdie officialoffizielle guide.Anleitung von BookStack.

FullVollständiges BookStack BookStack-Backup (Docker) —– soso, adass moveein toUmzug auf anotheranderen server/domainServer/Domain worksklappt 🧰📦

ForDu abrauchst für eine complete,komplette, restorablewiederherstellbare backupSicherung, youim essentially needWesentlichen twozwei componentsBausteine:

  1. DatabaseDatenbank (allalle pages,Seiten, books,Bücher, users,Nutzer, permissions,Rechte, settingsEinstellungen …)
  2. Files/configDateien/Config (uploads,Uploads, attachments,Anhänge, .env/APP_KEY, possiblyggf. themes/modules)Themes/Module)

SinceDa yourdu setupdas matchesSetup yourwie guidein deiner Anleitung hast (/opt/bookstack withmit docker-compose.yml, volumesVolumes ./mariadb andund ./bookstack), thisist isdas pleasantlyerfreulich simple.simpel.

✅ WhatWas exactlygenau needsmuss togesichert be backed up?werden?

1) DatabaseDatenbank (MariaDB)

  • TheInhalt contentsteckt isim DB-Container, in thedeinem DBSetup container,dauerhaft and in your setup it’s persisted under:unter:
    • ./mariadb (asals the volumeVolume ./mariadb:/config)
  • CleanestSauberster approachWeg: SQL dumpSQL-Dump (portable,portabel, tolerant across versions)versionstolerant)

2) FilesDateien (BookStack container volume)BookStack-Container-Volume)

  • PersistentPersistente dataDaten isliegen storedbei under:dir unter:
    • ./bookstack (asals the volumeVolume ./bookstack:/config)
  • InDarin particular,sind theseinsbesondere are important:wichtig:
    • .env (including theinkl. APP_KEY!)
    • uploads/attachmentsUploads/Attachments
    • possiblyggf. www/themes/custom/... (yourdeine tweaks/modules)Hacks/Module)

3) Compose/Caddy (helpfulfür forden migration)Umzug hilfreich)

  • docker-compose.yml
  • Caddyfile
  • CaddyCaddy-Daten data (optional):optional:
    • ./caddy/data & ./caddy/config (certificates/state)Zertifikate/State).
      NotNicht strictlyzwingend requirednötig, butaber sometimesspart savesmanchmal you from re-issuing / rate limits.Re-Issue/Rate-Limits.

🗂️ CreateBackup a backuperstellen (recommendedempfohlenes approach)Vorgehen)

Assumption:Annahme: theProjekt project isliegt in /opt/bookstack andund thedie containersContainer areheißen named aswie in yourdeiner YAML:
bookstack-mariadb andund bookstack.

StepSchritt 1: CreateBackup-Ordner a backup folderanlegen

cd /opt/bookstack
mkdir -p backups

Schritt 2: Datenbank als SQL dumpen 💾

docker exec -i bookstack-mariadb \
  mysqldump -u bookstack -pbookstack \
  --single-transaction --routines --triggers \
  bookstack > backups/bookstack-db-$(date +%F).sql

Wichtig: Ersetze -pbookstack durch dein echtes Passwort (aus MYSQL_PASSWORD).

Alternativ (sicherer, weil Passwort nicht in der Shell-History landet):
Lass -p... weg, dann fragt mysqldump interaktiv nach dem Passwort:

docker exec -it bookstack-mariadb mysqldump -u bookstack -p --single-transaction --routines --triggers bookstack > backups/bookstack-db-$(date +%F).sql

Schritt 3: Dateien/Volumes archivieren 📦

tar -czvf backups/bookstack-files-$(date +%F).tar.gz \
  docker-compose.yml Caddyfile \
  bookstack mariadb caddy

Wenn du Caddy nicht mitsichern willst, geht auch schlanker:

tar -czvf backups/bookstack-files-$(date +%F).tar.gz \
  docker-compose.yml Caddyfile \
  bookstack mariadb

Schritt 4: (Optional) Integritätscheck ✅

ls -lh backups/
head -n 5 backups/bookstack-db-*.sql
tar -tzf backups/bookstack-files-*.tar.gz | head

🔁 Restore (auf neuem Server) – inkl. Domain/URL-Umzug

Schritt 0: Voraussetzungen

    Docker + Docker Compose installiert DNS der neuen Domain zeigt auf den neuen Server (für HTTPS via Caddy)

    Schritt 1: Backup rüberkopieren

    Auf alten Server packen oder direkt kopieren:

    scp -r /opt/bookstack/backups user@neuer-server:/opt/bookstack/

    Schritt 2: Dateien wiederherstellen (Compose/Volumes) 📂

    Auf dem neuen Server:

    cd /opt/bookstack
tar -xvzf backups/bookstack-files-YYYY-MM-DD.tar.gz

    (Datum natürlich anpassen.)

    Schritt 3: Container starten (DB soll schon laufen) 🐳

    cd /opt/bookstack
docker compose up -d mariadb

    Warte ein paar Sekunden, bis MariaDB bereit ist.

    Schritt 4: Datenbank importieren 🧩

    cat backups/bookstack-db-YYYY-MM-DD.sql | \
  docker exec -i bookstack-mariadb mysql -u bookstack -pbookstack bookstack

    Wieder: Passwort anpassen bzw. interaktiv nutzen.

    Schritt 5: BookStack starten

    docker compose up -d

    🌍 Domain/URL geändert? (sehr wichtig!)

    Wenn du auf eine andere URL/Domain umziehst, musst du:

    1) APP_URL im .env anpassen

    In deinem Volume liegt die .env typischerweise unter:

      ./bookstack/www/.env (häufig bei linuxserver/bookstack) oder ./bookstack/.env (je nach Image/Setup)

      Suche sie so:

      find /opt/bookstack/bookstack -maxdepth 3 -name ".env" -print

      Dann APP_URL=https://neue-domain.tld setzen.

      Achte darauf: Die APP_KEY muss die alte bleiben (sonst gehen u.a. verschlüsselte Daten kaputt, z. B. MFA-Secrets).

      2) BookStack-Command: „Update System URL“

      Damit Inhalte/Links in der DB sauber umgeschrieben werden:

      docker exec -it bookstack php /app/www/artisan bookstack:update-url https://alte-domain.tld https://neue-domain.tld

      (Falls der Pfad im Container anders ist, funktioniert oft auch: php artisan ... aus /app/www.)

      🧠 Praktische Hinweise (damit’s wirklich „umzugsicher“ ist)

        Backup immer offsite speichern (anderes System/Storage).

        Datenbank-Dump + Datei-Archive ist am portabelsten.

        Wenn du auf eine neuere BookStack-Version wiederherstellst:

          Restore DB

          Container hoch

          Dann Migration laufen lassen (falls nötig):

          docker exec -it bookstack php /app/www/artisan migrate --force

          Wenn du willst: Ich mache dir ein „1-Kommando-Backup-Skript“ 🧾

          Sag mir kurz:

            Liegt deine .env unter bookstack/www/.env? Wie heißen deine Container wirklich (docker ps-Auszug)? Willst du Caddy-Zertifikate mitsichern oder lieber nicht?

            Dann gebe ich dir ein kleines Skript inkl. Rotation (z. B. „halte die letzten 7 Backups“) und optionalem Upload zu S3/Hetzner Storage Box.

            Back to top