﻿# Upgrading, backup and restore

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

Source: https://workwise-solutions.net/docs/installation/upgrade-backup-restore/ · Language: en · Hungarian version: https://workwise-solutions.net/hu/docs/installation/upgrade-backup-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.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](https://workwise-solutions.net/docs/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.

![Upgrading, backup and restore](https://workwise-solutions.net/docs/images/diagram-upgrade-backup-en.png)
*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)](https://workwise-solutions.net/docs/installation/windows-iis/#updating), [Linux](https://workwise-solutions.net/docs/installation/linux/#updating), [Kubernetes](https://workwise-solutions.net/docs/installation/kubernetes/#operations).

## 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.
