# Backups and upgrades

> What to copy to back up a workspace, how an upgrade migrates it, and how to go back.

Source: https://alexgalhardo.github.io/vukem-video/docs/self-hosting/backups-and-upgrades/

## You will learn

- what a complete backup contains and how to take one safely;
- what an upgrade does to the workspace;
- how to roll back.

## The idea

Everything is in one directory, the [workspace](/docs/workspace) (`/data` in the container, `~/.vukem-video` otherwise). A complete backup is that directory. The parts that matter:

| Path | Keep? |
| --- | --- |
| `db.sqlite` | yes: projects, history, jobs, users, keys |
| `store/` | yes: your imported originals, by content hash |
| `exports/` | yes: the files you made |
| `artifacts/`, `frames/` | no: they are rebuilt from the originals |
| `backups/` | the database copies the server makes before a migration |
| `logs/` | optional |

On a graceful shutdown the server checkpoints the database, so `db.sqlite` is self-contained when copied by hand. Never copy the workspace while the server runs: stop the container or the server first, copy, then start it again.

## Quick start

```bash
docker stop vukem-video
docker run --rm -v vukem-video:/data -v "$PWD":/backup debian:13.7-slim \
  tar -czf /backup/vukem-video-data.tar.gz -C /data .
docker start vukem-video
```

To upgrade, pull the new tag and recreate the container with the same volume and the same `APP_KEY`:

```bash
docker pull ghcr.io/alexgalhardo/vukem-video:X.Y.Z
docker stop vukem-video && docker rm vukem-video
# run the same docker run command as before, with the new tag
```

On start the server checks the database. If migrations are pending and the workspace is not new, it first writes `backups/db--before-<migration>.sqlite` and keeps the five newest, then migrates. A project document written by an older version is migrated when it is opened, and the original is kept in the database. Read the [changelog](/changelog) before a minor upgrade: before `1.0.0` a minor release may change a public interface.

To roll back, stop the server, restore the backup (or the `backups/db-*-before-*.sqlite` file as `db.sqlite`) and start the older tag. A workspace migrated by a newer version may not open in an older one, which is why you take the backup first. The older version then refuses to start, changes no file and says `this workspace was written by a newer version`, followed by what it found; the fix is to install a version at least as new, or to restore the backup.

### What is tested

Every release candidate is opened against workspaces written by the published releases from `v0.3.0` on. The `upgrade` workflow runs on every pull request labelled `release` and on every tag, on Linux, Windows and macOS. It downloads the archive of each release, checks it against `checksums.txt`, lets that release create a workspace with a fixed project (captions, keyframes, a template, trash and restore, an export), and then checks that the new build opens each one, writes a backup before migrating, keeps the five newest backups, loses no project and changes no document. It also checks that each older binary refuses a workspace written by the new build. To run it yourself, from a checkout, with `go`, `ffmpeg`, `ffprobe`, `jq` and `gh` installed:

```bash
bash scripts/upgrade-test.sh v0.5.0 v0.14.0
```

Without arguments the script tests every published release from `v0.3.0` on.

## Common mistakes

- Backing up only the database. Without `store/` your imported media is gone.
- Using the tag `latest` on a server you keep. Pin `X.Y.Z` and move it on purpose.
- Running the new and the old container on one volume at the same time: the second fails with `E_WORKSPACE_LOCKED`.
- Losing `APP_KEY`: keep it with your other secrets.

## Next steps

- [Verify a release](/docs/self-hosting/verify-a-release)
- [Troubleshooting: the diagnostic bundle](/docs/troubleshooting/diagnostic-bundle)
