Versioning & releases

Taranac is shipped as a small set of containers that run as one stack. To keep upgrades predictable, the project versions software along deployment boundaries, not along source directories. As an operator you mostly deal with one number — the platform version — plus an independent number for the optional push-MFA service. This page explains what each version covers, what actually guarantees compatibility, and where to read the running version and the applied database migration from the admin UI.

There are two independent version lines. They move on their own cadence and are not expected to match each other.

At the time of writing the platform line is at 1.0.8. Both lines follow a MAJOR.MINOR.PATCH (semantic-versioning) shape, but see What versions don’t tell you below — for an operator the contracts matter more than the number.

The platform version has a single source of truth: the VERSION file shipped in the deployment bundle (deploy/dist/VERSION), which is baked into the container images at build time. It is not a runtime .env value — you don’t set APP_VERSION in your environment; the version is fixed by the image tag you deploy. This removes any chance of the reported version drifting from the images actually running.

A single platform version pins the whole AAA/NAC stack together: the admin UI you log into, the AAA engines that answer device requests, the captive-portal frontend, and — crucially — the database schema that backs all of it. When you move from one platform version to another, all of these move as a set. You should not run a backend of one version against a frontend or a daemon configuration of another; that combination is untested and unsupported.

The platform stores its configuration and logs in a relational database. Each platform release that changes the schema ships one or more migrations — ordered, numbered scripts that bring an existing database forward to the new layout.

Migrations are applied automatically: on container startup the backend runs the pending migrations up to the latest (“head”) before the application begins serving. In practice this means an upgrade is pull the new images, restart the stack — the schema is brought current for you. You do not run migrations by hand in normal operation.

The migration cadence follows the release cadence: a release that needs a schema change includes the migration for it, so the applied migration on a healthy system corresponds to the platform version that introduced it.

The dashboard’s System Info widget is the operator-facing place to read what is actually running. It shows:

The dashboard System Info widget reports the running platform version and the applied schema migration.

The platform version is also shown in the admin-UI footer (as v<version>) and on error pages, so it is visible even when you are not on the dashboard.

For automation and health checks, the backend exposes HTTP probes:

GET /healthz   →  { "status": "ok" }            # liveness only
GET /ready     →  { "status": "healthy",
                    "version": "1.0.8",
                    "uptime_seconds": 1234,
                    "checks": { "database": "ok",
                                "master_key": "loaded" } }

/healthz is a bare liveness probe and returns no version. The version, uptime and component health live on /ready — use that endpoint if you want to read the running version programmatically. status is healthy only when the database is reachable and the master key is loaded; otherwise it reports degraded.

A version number does not, by itself, guarantee that two components will interoperate. Real compatibility lives in contracts:

• Backend ↔ TACACS+/RADIUS/NAC daemons — the format of the configuration the backend generates for the daemons.
• Backend ↔ taranac-mfa — the HTTP API between them.

Bumping a number does not protect against a broken contract, and matching numbers across the two version lines do not imply compatibility. This is why the platform components are versioned and released as one unit: it removes the question of “which backend goes with which daemon” entirely. For push-MFA, keep the taranac-mfa service and the mobile app on releases that share the same API contract.

When you upgrade the platform:

1. Back up first (configuration and database) — see Backups & upgrades.
2. Pull the new platform images and restart the stack. Pending migrations apply automatically on startup.
3. Confirm the result in System Info: the Version should reflect the new release and Migration should advance to the new head. /ready should report healthy.

When you upgrade the push-MFA service, treat it as its own unit: its version moves independently, and what matters is that its API contract stays compatible with the mobile app in use.

• Backups & upgrades — the recommended backup-then-upgrade procedure.
• Architecture — how the platform components and daemons fit together.
• Settings reference — configuration surface of the platform.
• Taranac on GitHub — the deployment bundle, releases and tags.