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 (/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#
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-videoTo upgrade, pull the new tag and recreate the container with the same volume and the same APP_KEY:
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 tagOn start the server checks the database. If migrations are pending and the workspace is not new, it first writes backups/db-<UTC timestamp>-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 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 scripts/upgrade-test.sh v0.5.0 v0.14.0Without 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
lateston a server you keep. PinX.Y.Zand 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.