Upgrade your instance

Upgrading KolleK is designed to be boring: pull the newer version, rebuild, done. This page explains why that is safe, and the one post upgrade step to know about.

Why upgrades do not lose data

Two properties make the upgrade path safe:

• Your data lives in named volumes (db-data for the database, storage-data for files), independent of the containers and the image. Rebuilding containers does not touch them.
• Migrations are forward only. The web container applies pending database migrations on boot with migrate --force, and KolleK never ships a migration that resets or destructively rewrites data. An upgrade only ever adds to your schema.

Upgrade

git pull

docker compose up -d --build

If you prefer migrations under manual control, set RUN_MIGRATIONS=false and run docker compose exec app php artisan migrate --force yourself as part of the procedure, as covered in Install with Docker.

The photo search index step

One upgrade includes a one time maintenance task: instances that predate the photo library screen need their photo search index built once, or photo search stays empty for existing photos.

docker compose exec app php artisan photos:rebuild-search-index

The command is idempotent and safe to run on any instance, so when in doubt, run it. It also backfills image dimensions for photos uploaded before dimensions were recorded.

The account search index step

Search across your account reads an index of its own. The migration creates the table, but only the rebuild command fills it, so on an existing instance search finds nothing until it has run once:

docker compose exec app php artisan search:rebuild-index

It walks every record in every account, so give it a moment on a large instance. From then on the index keeps itself up to date as records change. See Search across your account.

Where to next

• Keep backups current so every upgrade starts from one.
• Review Scheduled maintenance jobs, which resume automatically once the scheduler container is back up.