Upgrading

An upgrade is an image swap. Everything Sondar keeps — indexes, the metadata store, uploaded files, apps — lives in the data volume mounted at /usr/share/sondar/var, so a new image started on the same volume picks up where the old one stopped. The steps below were run end to end on 1 Oct 2026, from an install made by a 29 Sep build to the current one and back again.

---

1. Copy the volume first

This copy is your rollback. Take it with the server stopped, so the files are not changing under the copy:

docker stop -t 90 sondar
docker run --rm -v sondar-data:/from:ro -v sondar-data-backup:/to \
  alpine:3 cp -a /from/. /to/

docker stop -t 90 sends the server a normal shutdown and gives it up to 90 seconds to finish writing; it exits on its own well inside that (2 seconds on the test install, exit code 143, which is the expected code for a shutdown signal). Do not use docker rm -f or docker kill on a running server: those end it without that write, and the metadata store can be left unreadable.

A volume holding a fresh install is about 165 MB and copies in a second; yours grows with the data you keep, so leave room for a second copy of it.

2. Start the new image on the same volume

Remove the old container (the volume is not touched) and start the new image with the same flags and the same volume:

docker rm sondar
docker run -d --name sondar -p 9200:9200 \
  -v sondar-data:/usr/share/sondar/var sondar:<new-tag>

The server brings the database up to date before it serves anything. The log says what it did:

docker logs sondar 2>&1 | grep 'schema'

schema migrations applied: 21 -> 23 (2 migration(s))

When there is nothing to apply it says schema is up to date at 23. Then wait for readiness, which needs no login:

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:9200/api/v1/readyz

200 means it is serving. On the test install that took under 20 seconds, migrations included. Migrations only move forward and run in order, so you can skip versions: an install two migrations behind took both in one start.

3. What upgrades by itself, and what does not

• The server, the UI and the agent installers are in the image, so they are the new version as soon as it starts.
• Built-in apps update their own code and pages on the first start of a new build. The things inside an app that you can edit — dashboards, saved searches, collection types and the like — do not change by themselves, so an upgrade never overwrites your edits. Manage Apps offers an Update for each app whose version moved, and asks before it replaces anything you changed. How an app upgrade reaches a running install covers the detail.
• Agents are not upgraded by the server image. Upgrade them from Agent and machines when you choose to.

From 20 Oct 2026 the server does not run as root

Images built from 20 Oct 2026 run the server as the user sondar, uid and gid 10001, instead of root. Nothing changes in the steps above:

• The data volume is taken over on the first start. A volume an older image wrote belongs to root. The container starts as root only long enough to give sondar whatever in /usr/share/sondar/var — and in /usr/share/sondar/share, if you mount a volume several containers share there — is not already its own, then starts the server as sondar. Later starts check everything again except the index files in var/data, which after the first start only the server writes; a start with SONDAR_RUN_AS_ROOT=true makes the next one check those too. If you copy a file into var/data yourself as root, give it to uid 10001.
• A file you mount in and name in a setting must be readable by uid 10001 — in practice the private key from Serving HTTPS, which is often root’s with mode 600. Such a file stops the start with a message that names it, its owner and mode, and the fix: on the host, sudo chgrp 10001 key.pem && sudo chmod 640 key.pem.
• To keep running as root, start the container with -e SONDAR_RUN_AS_ROOT=true.
• On Kubernetes, the Helm chart runs the server pods as 10001. Before the server starts, a short init container gives the data and share volumes to 10001 — it runs as root with only the right to change owners, then exits — because Kubernetes’ own fsGroup is not applied to NFS volumes, the usual backing of the chart’s shared volume. If your cluster’s admission policy refuses a root init container, set sondardb.takeOwnership.enabled=false and make sure the volumes already belong to uid 10001. The agent (sondard) still runs as root: it reads the host’s logs.

Rolling back is unchanged: an older image runs as root, and root reads files that belong to sondar.

Which build am I running?

docker exec sondar cat /usr/share/sondar/.commit

prints the source revision the image was built from.

How long a release is supported

• Each minor release is supported for 12 months from the day it is released.
• Fixes, including security fixes, are provided in the latest minor release. An older release inside its 12 months still gets help, but taking a fix means upgrading to the latest minor release.

Versioned releases have not started yet. Until the first one, there is a single line, and every image moves forward by the steps on this page.

---

Rolling back

Restore the copy from step 1, then start the image you came from:

docker stop -t 90 sondar && docker rm sondar
docker run --rm -v sondar-data:/to -v sondar-data-backup:/from:ro \
  alpine:3 sh -c 'rm -rf /to/* /to/.[!.]* 2>/dev/null; cp -a /from/. /to/'
docker run -d --name sondar -p 9200:9200 \
  -v sondar-data:/usr/share/sondar/var sondar:<old-tag>

On the test install the old image started on the restored volume with schema is up to date at 21, ready, and no errors.

Do not roll back by starting the old image on the upgraded volume. It will start — it logs only a warning that the schema has a version (23) that is newer than the latest available migration (21) — but nothing guarantees the older build can work with what the newer one changed. Migrations can delete data the old build still expects (two recent ones removed saved connections to database types that were dropped), and there is no step that puts it back. The copy is the rollback; anything you ingested after the upgrade is not in it, so take the copy as close to the upgrade as you can.

If the server will not start because the metadata store will not open — readiness never answers 200 and the log says File corrupted while reading record: ".../var/h2.mv.db" — restore the copy as above. In our tests that happened 4 times in 23 when an older build was started on a volume a newer one had just stopped, before the 20 Oct 2026 build: the embedded store was closed by the Java runtime while the server was still writing to it. Builds since then close it themselves, after everything else has stopped. The rows themselves survived in the damaged store we examined, so keep the volume rather than deleting it if you have no copy, and contact us.