Upgrading, backup and restore
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.jsonholds 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#
- Read the release notes: they list the steps a version needs, if any, and whether it needs a newer .NET runtime.
- Back up the database and the data folder or volume.
- Replace the application files (or the image), keeping your
appsettings.json. - 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.jsonwith defaults.
To go back to an earlier version, restore the backup taken before the upgrade: migrations are never reversed.
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):
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 worksmarthubRestore (with the application stopped; this replaces the whole volume):
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 setPublicBaseUrlto 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.