Upgrade¶
Kist's migrations run when the app starts, and every new piece of data is a plain file in the library, so an upgrade is: back up, pull, rebuild, run the one-off backfills the release notes name. The full notes for each version are in CHANGELOG.md.
Every upgrade¶
cd kist
docker compose exec db pg_dump -U kist kist | gzip > kist-before-upgrade.sql.gz
git pull
docker compose build && docker compose up -d
docker compose logs app | grep -E "Running upgrade|ERROR"
docker compose exec worker kist selftest
The database dump is the quick way back. The library itself is never rewritten
by a migration, and kist rebuild-index can rebuild the database from it
anyway.
From 1.5 to 2.0¶
In this order:
- Back up the database (above).
- Switch the database image to
pgvector/pgvector:pg16. Kist'sdocker-compose.ymlalready uses it; it is the officialpostgres:16image plus the pgvector extension, so it opens your existingpgdatavolume as is. If you keep your own compose file, changeimage: postgres:16toimage: pgvector/pgvector:pg16. Stay onpg16. - Decide about the trash. It now empties itself after 30 days; set
KIST_TRASH_RETENTION_DAYS=0first to keep it forever. docker compose pull db && docker compose build && docker compose up -d. The migrations run on start, one line each.-
One-off backfills, all safe to re-run, best as one detached chain so you can close the SSH session:
docker compose exec -d worker sh -c '( echo "== rewrite-meta"; kist rewrite-meta; echo "== geo-download"; kist geo-download; echo "== media-backfill"; kist media-backfill; echo "== colors"; kist regen-previews --colors-only; echo "== thumbnails"; kist regen-previews --thumbs-only; echo "== ai-backfill"; kist ai-backfill; echo "== verify"; kist verify; echo "== ALL DONE") > /library/upgrade.log 2>&1' tail -n 3 library/upgrade.log # later: the last step it reachedgeo-downloadis optional (about 10 MB from GeoNames, once; it names the places of photos with GPS). The commands print nothing until they finish; on a NAS,rewrite-metaandmedia-backfilleach take roughly 10–20 minutes per 4,000–5,000 items, and AI embeddings 1.5–2.5 hours per 100,000 items (setKIST_AI_WINDOW=01:00-06:00to keep that at night). Watch progress withdocker compose exec worker sh -c 'find /library/items -name meta.json -mmin -2 | wc -l'.regen-previews --thumbs-onlyis the exception: it prints a progress line with a time estimate every 200 items (grep thumbnails: library/upgrade.log | tail -n 1); expect roughly 2–3 hours per 17,000 items on an N100. -
New files to back up with the library:
items/*/ai/,boards/,vocabulary.json,.kist/(tokens, people, templates, shares, export presets) and the itempage/snapshots. Backing up the whole library folder covers them all. Theml-modelsvolume needn't be backed up.
Optional extras: captions (AI), faces (KIST_FACES=1), map tiles
(Maps), Intel GPU video encoding (KIST_HWACCEL=vaapi).
Going back¶
Stop the app, worker and ml services, restore the dump into a fresh database, check out the previous version and rebuild. 2.0's extra files beside your items are ignored by 1.5.