Skip to content
Kindo Sift Kindo Sift Kindo Sift

Upgrade Sift

An upgrade replaces the images and the release’s files, keeps the data volumes, and lets sift-api migrate the database when it starts. This page is the procedure every upgrade follows. Each release adds its own steps, which can matter more than the procedure: read them first.

Before you start

Section titled “Before you start”
  • Read the new release’s notes. Each release ships CHANGELOG.md, which says what changed, and docs/upgrading.md, which says what an operator does about it, release by release. Some steps must happen before the new stack starts.
  • Find the release you run. /api/healthz reports it as version, and so does the VERSION file in the directory you deploy from.
  • Skipping releases? Do the steps of every release between yours and the new one, in order, oldest first. Each release’s steps assume the stack is on the release before it.
  • Plan a short outage. While the stack is down nothing is polled, scored or sent. Nothing is lost: each filter resumes from where it last read its source.

Upgrade

Section titled “Upgrade”

  1. Take a backup with the release you are running, and note the directory it prints:

    Terminal window
    ./scripts/backup.sh

    The script acts on the Compose project kindo-sift unless told otherwise. If you deploy from a directory with another name, add -p <project> (docker compose ls lists it), here and for restore.sh below.

  2. Copy .env somewhere the backup is not. It holds SIFT_SECRET_KEY, which the backup does not, and without which the stored Kindo key and webhook secrets cannot be read.

  3. Stop the stack, with the release you are running:

    Terminal window
    make down

    make down keeps every volume. Run it before you replace the files, so it acts on the services the old compose file defines.

  4. Put the new release’s files in place, in the same directory: Compose names the project, and so the data volumes, after the directory, and a new directory name would start on new, empty volumes. Then get the new images: load its image bundle (gunzip -c kindo-sift-<version>-images.tar.gz | docker load), or run make build if you build from source. The compose file names the release’s image tags, so the new images must be on the host before you start.

  5. Make any .env changes the release’s notes ask for.

  6. Start the stack:

    Terminal window
    make up

    sift-api applies the database migrations as it starts, before it serves anything, and the workers wait for it. Watch for migrations_done in its log:

    Terminal window
    docker compose logs -f sift-api

  7. Check the result: every service healthy in docker compose ps, every check ok at /api/readyz, and make smoke where you can run it (see what it does).

  8. Sign in and work through anything the release’s notes say needs a person. Some releases ask you to regenerate and re-import the paired agents Sift generated; when that is needed, the affected filters say so on their Actions tab.

Going back

Section titled “Going back”

There are no downgrade migrations. The way back is the backup you took in step 1, restored with the release it was taken on:

  1. Stop the stack: make down.

  2. Put the previous release’s files and images back.

  3. Restore the pre-upgrade backup:

    Terminal window
    ./scripts/restore.sh -i backups/<backup directory> --confirm

    The script starts the stack itself once the data is back, and then checks it.

Anything that happened between the upgrade and the restore is lost, as with any restore. See Back up and restore for what a restore rewinds.

Section titled “Related”