Versioning & upgrades

Perihelium uses semantic versioning — vX.Y.Z — and the meaning of each part is a guarantee we enforce in our own build pipeline, not a convention. It tells you exactly how much care an upgrade needs before you read the changelog.

How it works. The versioning and patching machinery this page describes is enforced in our own pipeline (the patch guard runs on every release tag). It is the contract your install runs under; see Deployment models.

What each part of the version promises

The important line is the first one. A patch is guaranteed to carry no schema migration and no new required setting — which is precisely what makes it safe to roll back automatically if anything goes wrong. That guarantee is checked by a release gate that fails our build if a patch tries to include either, so it is a property of the artifact you receive, not a promise on a page.

Applying a patch (self-service, unattended)

Patches are designed to apply themselves safely:

zynth-upgrade --patch

This resolves the latest patch in your current minor, verifies every image signature, records your current versions, snapshots the database as a precaution, deploys, and runs a smoke test — and if the smoke test fails, it rolls straight back to what you were running. Because a patch never changes the schema, that rollback is clean: your data is untouched and the previous images simply run again.

You can automate this. A patch that reaches you has already passed our full test suite and the patch gate; the advisory that announces a security fix ships with the patch already available.

zynth-upgrade needs bash and curl 7.55 or newer (any current Linux distribution has both). It sends your registry credentials as a header read from a pipe, never as a command-line argument, so other users on the host can't see them in the process list.

Your licence is checked before the upgrade runs

If your install carries a licence, zynth-upgrade checks its maintenance term before deploying anything. A current term proceeds; if you are inside the expiry-warning window it proceeds but warns you to renew; if the term has lapsed, the upgrade is refused with a clear message — new releases require a live maintenance term (you keep everything published while your term was active, forever). Renew and re-run. Installs with no licence configured are unaffected. This is a local safeguard; the same rule is enforced when you download a release, so the two never disagree.

Applying a minor or major

Minor and major upgrades can carry database migrations, so they do not self-apply. They run through a gated runbook: take a backup, apply, verify, with a defined restore point. Minor migrations are always backward-compatible within the minor (expand-then-contract), so a minor upgrade is low-drama — but it is a deliberate, backed-up step, not an unattended one. Major upgrades are planned with vendor assistance.

Which versions are supported

Security fixes are backported to the current minor and the one before it. Older minors need an upgrade to keep receiving fixes. This is published so it is a contract, not a case-by-case conversation — plan to stay within one minor of current.

If something goes wrong

Every upgrade path is reversible by design — a patch automatically, a minor/major from the backup the runbook takes first. If you need to open a support case, the support-bundle command produces a sanitized diagnostic archive (versions, configuration with secrets redacted, recent logs, health) so we can help without access to your infrastructure.

Next

• Self-hosting overview — the deployment shape and security posture.
• Deployment models — managed SaaS vs. self-host.