Operator reference

Release Process & Updates

Nexus release process, versioning, and recommended update process

Before you begin

This reference describes the underlying platform. Use a Nexus school release with its school membership, class policy, and cost controls. Installing a base engine alone does not add those controls.

This page explains Nexus's release process, versioning scheme, and how updates are delivered to different deployment channels.

Release Channels#

Nexus maintains multiple release channels to provide stable and development versions for different use cases.

GitHub#

Our GitHub Releases publish images to Docker Hub. Nexus has two types of releases:

Latest stable version - Production-ready releases
Pre-release version - Beta releases for testing

The main branch of the Nexus repository is our development branch.

Although we try to keep main stable through CI/CD tests and code reviews, we do not recommend using main in production environments.

Docker Hub#

Docker Hub hosts the actual container images. New images are published every night from the main branch and when a new release is cut.

To identify the latest images programmatically, use our API endpoint:

https://school.narb.cc/api/versions

This endpoint returns the current latest stable and beta versions available on Docker Hub.

If you don't specify a version when deploying Nexus, you will get the latest nightly builds.

Versioning Scheme#

Nexus follows Semantic Versioning (SemVer) with a clear, predictable format.

Standard Version Format:

major.minor.hotfix

Pre-release Version Format:

major.minor.hotfix-beta.betahotfix

Examples:

Stable release: 1.2.3
Pre-release: 1.3.0-beta.1
Beta hotfix: 1.3.0-beta.2

Major version - Incremented on breaking changes

Minor version - Incremented on new features, bugfixes, and backwards-compatible changes
Hotfix version - Incremented only when backporting bugfixes to releases

Docker Files and Helm Charts#

Changes to Docker files and Helm charts increment the version numbers in their respective files.

Release Schedule#

Nexus follows a predictable weekly release cycle.

Every Monday:

The last pre-release version is promoted to stable
main is frozen as the new pre-release

Hotfix Process#

Critical bug fixes are backported to stable releases as necessary
Hotfixes bypass the normal weekly cycle for urgent production issues
Both stable and pre-release branches receive hotfixes when applicable

Update Best Practices#

To maintain a stable deployment, we recommend staying on the latest stable release. These are tagged with a version number like v1.2.3.

Check Versions API for Stable Version Tag#

Compare your current version with the version tag of the latest stable release. The versions endpoint is public and does not require authentication.

  curl -X GET "https://school.narb.cc/api/versions"

Look for the stable: onyx key in the response.

  {
    "stable":{
      "onyx":"v1.8.1",
      "relational_db":"postgres:15.2-alpine",
      "index":"vespaengine/vespa:8.277.17",
      "nginx":"nginx:1.23.4-alpine"},
      "dev":{
        "onyx":"v1.9.0-beta.0",
        "relational_db":"postgres:15.2-alpine",
        "index":"vespaengine/vespa:8.277.17",
        "nginx":"nginx:1.23.4-alpine"
      },
      "migration":{
        "onyx":"airgapped-intfloat-nomic-migration",
        "relational_db":"postgres:15.2-alpine",
        "index":"vespaengine/vespa:8.277.17",
        "nginx":"nginx:1.23.4-alpine"
      }
    }
  }

Launch Nexus with the Version Tag#

How you launch the specific Nexus version will depend on your deployment process.

Don't forget the v prefix! I.e. v1.2.3 is correct, 1.2.3 is incorrect.

Docker Pull Images#

  Specify the version tag in the environment.

      IMAGE_TAG=<v.MAJOR.MINOR.HOTFIX> docker compose -f docker-compose.dev.yml -p onyx-stack up -d --pull always --force-recreate

Docker Build Images#

Pull the release branch from GitHub or just the tagged version and build the images.

The release branch is where the latest stable version is published.
Release branches are named `release/v<MAJOR>.<MINOR>`.

In the Nexus repo:

    git fetch origin release/v1.2
    git switch release/v1.2

    docker compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate

    git fetch origin tag v1.2.3
    git switch --detach v1.2.3

    docker compose -f docker-compose.dev.yml -p onyx-stack up -d --build --force-recreate

Helm#

To specify a version when deploying with Helm, set the `global: version` value in your `values.yaml` file.

    global:
      version: "v1.2.3"