Upgrading, backup and restore

Upgrading, backup and restore

On this page

What to back up#

Item Where
Internal database SQLite: database.db with database.db-wal and database.db-shm (always together). SQL Server, PostgreSQL, MySQL: with the database's own backup tools.
Server disk file storage FileStorage/ (attachments, component images)
Edited templates LiveEmailTemplates/, LiveNotificationTemplates/
Configuration appsettings.json
Logs (optional) Logs/

In Docker and Kubernetes everything except appsettings.json is on the data volume (/app/data). Cloud file storages are backed up at the provider.

Backups contain credentials. The database holds file storage keys, notification and e-mail credentials and other secrets in a form the application can decrypt, as well as the keys that protect sign-in cookies; appsettings.json holds the signing keys and connection secrets. Store backups with restricted access and encryption, and delete temporary copies.

Stop the application before copying a SQLite database: it runs in write-ahead-log mode, and a copy taken while it runs can be inconsistent.

Upgrading#

  1. Read the release notes: they list the steps a version needs, if any, and whether it needs a newer .NET runtime.
  2. Back up the database and the data folder or volume.
  3. Replace the application files (or the image), keeping your appsettings.json.
  4. Start the application. Database migrations run automatically at start-up. On several servers they run under a cross-node lock, so the servers can be upgraded together. New settings are added to appsettings.json with defaults.

To go back to an earlier version, restore the backup taken before the upgrade: migrations are never reversed.

The upgrade steps, what to back up, and how to go back.

Templates: IIS and Linux upgrades keep the edited live templates (the release contains only the defaults). In Docker, images whose live templates were inside the container lose them when the container is recreated; copy them out of the old container first (see the operator guide).

Platform-specific steps: Windows (IIS), Linux, Kubernetes.

Docker#

Backup (Linux; the helper reuses the application image and runs offline):

bash
docker stop worksmarthub
docker run --rm --network none -v worksmarthub-data:/app/data -v "$PWD":/backup --user "$(id -u):$(id -g)" \
  --entrypoint sh worksmarthub:23 -c 'umask 077; tar czf "/backup/worksmarthub-data-$(date +%F).tgz" -C /app/data .'
docker start worksmarthub

Restore (with the application stopped; this replaces the whole volume):

bash
docker run --rm --network none -u 0 --cap-drop ALL --cap-add CHOWN --cap-add DAC_OVERRIDE --cap-add FOWNER \
  -v worksmarthub-data:/app/data -v "$PWD":/backup:ro --entrypoint sh worksmarthub:23 \
  -c 'tar tzf /backup/worksmarthub-data-YYYY-MM-DD.tgz >/dev/null && find /app/data -mindepth 1 -delete && tar xzf /backup/worksmarthub-data-YYYY-MM-DD.tgz -C /app/data && chown -R 1001:1001 /app/data'

Upgrade: docker stop worksmarthub && docker rm worksmarthub, then run the new image with the same volume.

Keep the volume safe: named volumes survive docker rm and image upgrades, but docker volume prune -a, Docker Desktop's Clean / Purge data and Reset to factory defaults delete them. Take a backup before any of these.

Moving to another server or database#

  • Same database type: back up and restore the database and the data folder, copy appsettings.json (with the same signing keys, otherwise sessions, tokens and file links stop working), and set PublicBaseUrl to the new address. Attachment and image links are rebuilt for the current host automatically.
  • The Kubernetes operator guide has a section on migrating between environments.
Did not find what you need?

Write to us or book a call. We answer questions about features, installation and licensing.

Contact us