NiaDocs
Latest
Menu

Nia documentation · Latest

Backup and restore

Back up all Nia modules, recipe images, attachment files, account settings and keys, then restore a complete instance.

A complete Nia backup needs the SQLite database and runtime files. The database contains Tasks, Shopping, Recipes, sharing/household state, personal destination memory and recipe title-image bytes. Tasks attachments and avatars are separate files. Copying only the attachment directory loses recipes; copying only SQLite loses attachment files and runtime keys.

Debian package backups

The full server package installs a daily systemd timer:

sudo systemctl status nia-todo-backup.timer
sudo systemctl start nia-todo-backup.service

Create a manual backup:

sudo nia-todo-backup

By default, archives are stored in /var/lib/nia-todo/backups as nia-todo-daily-slot-NN.zip, with a matching JSON metadata file. The helper uses 30 rotating daily slots. Running it again on the same day replaces that day’s slot, so copy an important pre-upgrade archive elsewhere before the next run.

The archive contains a SQLite backup, its integrity-check result and runtime files under data/. The backup directory itself and transient SQLite files are excluded. SQLite is copied through its backup API, not by copying a live database file. The runtime-file copy is separate from that database snapshot; stop application writes for a planned migration or a strict, complete point-in-time copy involving attachments.

Restore a package backup

Stop the application before restoring:

sudo systemctl stop nia-todo
sudo nia-todo-restore /var/lib/nia-todo/backups/nia-todo-daily-slot-NN.zip
sudo systemctl start nia-todo

Replace NN with the slot you intend to restore. The helper checks the extracted database and restores the runtime snapshot. This replaces current content and removes stale runtime files that are absent from the archive; take a separate backup of the target first. Existing backup archives are preserved.

Docker backups

Run the packaged helper inside the running container:

docker compose exec nia-todo /app/scripts/nia-todo-backup.sh

With the documented /data layout, output is under /data/backups. Copy the archive outside the volume or include it in your normal backup system. A snapshot of a running SQLite volume is not automatically application-consistent. Use the SQLite-aware helper, or stop the container before a complete filesystem copy of its data volume.

Restore only while the application is stopped, using the matching restore helper/environment or a complete stopped-volume restore. Preserve the configured database path and container file ownership. Do not replace a database beneath a running server.

What to protect

Back up the configured NIA_TODO_DATA_DIR and the deployment configuration needed to reopen it:

  • SQLite, including every module, recipe images, account preferences, destination-memory history, grants and mutation receipts
  • Tasks attachment files and avatar files
  • generated application and VAPID keys
  • runtime configuration and instance-specific files
  • the Compose file or service environment, including separately managed secrets

Custom NIA_TODO_AVATAR_DIR, NIA_TODO_ATTACHMENT_DIR or NIA_TODO_VAPID_KEYS paths outside the main data directory are not automatically included by the packaged helper. Back them up separately. Environment files under /etc or beside a Compose file are also outside a normal data archive. Treat archives as sensitive: they contain private content and configuration.

Recipe images are already in the SQLite backup and do not need a separate recipe-image directory. Files that no longer count against an uploader’s quota still occupy disk space and remain part of the runtime backup while retained.

Move an instance or recover an upgrade

  1. Stop writes to the source instance.
  2. Create and preserve a final backup of its database, runtime files and deployment configuration.
  3. Install the same or a newer compatible Nia build on the target, without using it for new content.
  4. With the target application stopped, restore the archive and any external paths.
  5. Start the target and verify users, Tasks, Shopping lists, cookbooks, recipe images, attachments and current sharing permissions with the relevant accounts.
  6. Check the public URL, provider settings, email and native-client connection before changing DNS or the reverse proxy.

V4 applies numbered migrations on startup, including conversion of older BrainDump destination learning into the shared memory system. Preserve the pre-V4 backup. A migrated database is not a supported rollback to 3.x; restore the earlier database and matching runtime files with the earlier application instead.

Keep a copy outside the Nia host and test a restore periodically. Browser offline queues are device-local and are not in a server backup; synchronize important pending changes before moving the server.

Implementation reference: the backup helper defines the archive layout and retention; the restore helper defines replacement and cleanup behavior.