Skip to content

Backup and restore

A backup is a ZIP file of the whole instance: all users, settings, categories, guides with their working copies, all their versions and the deleted ones, pages, the menu, the problem reports, and every image and attachment. Admins download it in kataba; it is restored on the command line, into a new, empty instance, for example to move kataba to another server.

Downloading a backup

Administration → Download backup downloads a backup, named after the day, such as kataba-backup-2026-11-05.zip. kataba writes it while it is downloaded, so it starts at once; with many images it can grow to several GB.

A backup holds all content, internal and deleted guides included, so keep it as safe as the server.

Backups of the server

A backup from kataba is one way to keep the instance safe. Backing up the server, the database and the upload directory (UPLOAD_DIR, or the volumes with Docker), is another; both work.

Restoring a backup

A backup is restored only into an empty instance: freshly installed, with the schema applied, before anyone has signed in. Nothing is merged or overwritten; an instance that holds anything refuses the restore.

  1. Install a new instance, or start one with Docker, with its own empty database and upload directory. Don't sign in yet.
  2. Run the restore command with the backup:

    docker compose cp kataba-backup-2026-11-05.zip kataba:/tmp/backup.zip
    docker compose exec kataba npm run restore -- /tmp/backup.zip
    
    npm run build:restore   # once, builds the restore command
    npm run restore -- kataba-backup-2026-11-05.zip
    
  3. Restart kataba, so that it drops what it remembered of the empty instance, e.g. docker compose restart kataba.

Guides, categories, pages and everything else with an address keep their ids, so links and labels with a QR code keep working, as long as the new instance has the same address. Users sign in as before; their roles are derived anew from their groups in Authentik.

The backup holds the SMTP server's password of the email settings only encrypted with the instance's AUTH_SECRET. Give the new instance the same AUTH_SECRET to keep it; otherwise kataba cannot read it, and you enter it again in the settings.

A backup written by a newer kataba is refused: update the new instance first.